diff --git a/.gitignore b/.gitignore index a3d79ef..cbce07a 100644 --- a/.gitignore +++ b/.gitignore @@ -9,8 +9,8 @@ node_modules/ dist/ # Local Env Files -.env.local -.env.*.local +.env +.env # Log files *.log diff --git a/README.md b/README.md index 7b8a3ef..6061766 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,28 @@ -# AnimeThemes API Docs +

+ + + + +

-This is the repository for the AnimeThemes.moe API Docs powered by [VuePress](https://vuepress.vuejs.org/), a minimalistic static site generator. +## Introduction + +AnimeThemes is a simple and consistent repository of anime opening and ending themes. We provide direct links to high quality WebMs of your favorite OPs and EDs for your listening and discussion needs. + +The AnimeThemes API provides access to our repository resources for your development needs. + +This is the repository for the AnimeThemes.moe API documentation. + +This project is powered by [VuePress](https://vuepress.vuejs.org/), a minimalistic static site generator. ## Installation -Fork this repository. - -Clone the forked repository. - -Install dependencies. +In the project root directory, install dependencies. `npm install` -Build docs. +In the project root directory, start the local development server. -`npm run dev` \ No newline at end of file +`npm run dev` + +That's it! The local development server should be running at `localhost:8080`. \ No newline at end of file diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index a337ac6..ba981e3 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -1,4 +1,7 @@ +require('dotenv').config() + module.exports = { + base: process.env.VUEPRESS_BASE, description: 'AnimeThemes API Documentation', theme: 'api', themeConfig: { @@ -10,6 +13,10 @@ module.exports = { { title: 'JSON:API', to: '/jsonapi' + }, + { + title: 'Rate Limiting', + to: '/ratelimiting' } ] }, diff --git a/docs/README.md b/docs/README.md index f13bef0..7fd6685 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,11 +16,11 @@ The AnimeThemes API selectively implements the [**JSON:API Specification**](http We provide an overview of where the AnimeThemes API adheres to or deviates from the specification. -## Rate Limiting +## [Rate Limiting](/ratelimiting) The AnimeThemes API applies the standard named rate limiter of the Laravel Framework. -Please limit requests to 1/sec. +We provide an overview of managing request quotas. ## Terms of Use @@ -32,4 +32,4 @@ For API support, please make use of the **#development** channel in the [**Disco To report an issue with or request a new feature for the API, please make use of the [**animethemes-server**](https://github.com/AnimeThemes/animethemes-server) Github. -To report an issue with or request a new feature for this documentation, please make use of the [**animethemes-api-docs**](https://github.com/AnimeThemes/animethemes-server) Github. \ No newline at end of file +To report an issue with or request a new feature for this documentation, please make use of the [**animethemes-api-docs**](https://github.com/AnimeThemes/animethemes-api-docs) Github. \ No newline at end of file diff --git a/docs/anime/README.md b/docs/anime/README.md index 44d90e0..d19f256 100644 --- a/docs/anime/README.md +++ b/docs/anime/README.md @@ -12,17 +12,17 @@ For example, Bakemonogatari is an anime production with five opening sequences a ### Fields -| Name | Type | Description | -| :--------: | :-----: | :-------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| name | String | The primary title of the anime | -| slug | String | The URL slug & route key of the resource | -| year | Integer | The premiere year of the anime | -| season | Enum | The premiere season of the anime {Winter, Spring, Summer, Fall} | -| synopsis | String | The brief summary of the anime | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :-------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| name | String | No | The primary title of the anime | +| slug | String | No | The URL slug & route key of the resource | +| year | Integer | Yes | The premiere year of the anime | +| season | Enum | Yes | The premiere season of the anime {Winter, Spring, Summer, Fall} | +| synopsis | String | Yes | The brief summary of the anime | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/anime/index/README.md b/docs/anime/index/README.md index 6761470..a944aef 100644 --- a/docs/anime/index/README.md +++ b/docs/anime/index/README.md @@ -49,8 +49,6 @@ GET /api/anime/ ## Response ```json -Status: 200 - { anime: [ { diff --git a/docs/anime/show/README.md b/docs/anime/show/README.md index 4489935..e351d42 100644 --- a/docs/anime/show/README.md +++ b/docs/anime/show/README.md @@ -27,8 +27,6 @@ GET /api/anime/{slug} ## Response ```json -Status: 200 - { anime: { id: id, diff --git a/docs/announcement/README.md b/docs/announcement/README.md index 3a3d52b..b191bc9 100644 --- a/docs/announcement/README.md +++ b/docs/announcement/README.md @@ -12,13 +12,13 @@ For example, if video streaming is disabled, the site staff may issue a "Video s ### Fields -| Name | Type | Description | -| :--------: | :-----: | :-------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| content | String | The announcement text | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :--------------------------------------------| +| id | Integer | No | The primary key of the resource | +| content | String | No | The announcement text | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/announcement/index/README.md b/docs/announcement/index/README.md index dc51da8..f9e81e6 100644 --- a/docs/announcement/index/README.md +++ b/docs/announcement/index/README.md @@ -42,8 +42,6 @@ GET /api/announcement/ ## Response ```json -Status: 200 - { announcements: [ { diff --git a/docs/announcement/show/README.md b/docs/announcement/show/README.md index 832df70..b4ba06a 100644 --- a/docs/announcement/show/README.md +++ b/docs/announcement/show/README.md @@ -25,8 +25,6 @@ GET /api/announcement/{id} ## Response ```json -Status: 200 - { announcement: { id: id, diff --git a/docs/artist/README.md b/docs/artist/README.md index a04a498..4ba475f 100644 --- a/docs/artist/README.md +++ b/docs/artist/README.md @@ -12,15 +12,15 @@ For example, Chiwa Saito is the musical performer of the Bakemonogatari OP1 them ### Fields -| Name | Type | Description | -| :--------: | :-----: | :-------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| name | String | The primary title of the artist | -| slug | String | The URL slug & route key of the resource | -| as | String | Used to distinguish a performance by alias, character or group | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :-------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| name | String | No | The primary title of the artist | +| slug | String | No | The URL slug & route key of the resource | +| as | String | No | Used to distinguish a performance by alias, character or group | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/artist/index/README.md b/docs/artist/index/README.md index 7f3d671..9967a3a 100644 --- a/docs/artist/index/README.md +++ b/docs/artist/index/README.md @@ -45,8 +45,6 @@ GET /api/artist/ ## Response ```json -Status: 200 - { artists: [ { diff --git a/docs/artist/show/README.md b/docs/artist/show/README.md index 52cb139..bb7e6a1 100644 --- a/docs/artist/show/README.md +++ b/docs/artist/show/README.md @@ -27,8 +27,6 @@ GET /api/artist/{slug} ## Response ```json -Status: 200 - { artist: { id: id, diff --git a/docs/balance/README.md b/docs/balance/README.md index d14911d..8bcf1d8 100644 --- a/docs/balance/README.md +++ b/docs/balance/README.md @@ -10,17 +10,17 @@ A balance API resource represents an account balance against usage or upcoming c ### Fields -| Name | Type | Description | -| :-------------------: | :-----: | :------------------------------------------------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| date | Date | The given month that the account balance applies to | -| service | Enum | The service that is billing AnimeThemes {Other, DigitalOcean, AWS, Hover, WalkerServers} | -| frequency | Enum | The frequency that AnimeThemes is billed by the service {Once, Annually, Biannually, Quarterly, Monthly} | -| usage | Decimal | The amount of services consumed by AnimeThemes in the billing period | -| month_to_date_balance | Decimal | The balance of the AnimeThemes account with consideration to usage | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :-------------------: | :-----: | :------: | :------------------------------------------------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| date | Date | No | The given month that the account balance applies to | +| service | Enum | No | The service that is billing AnimeThemes {Other, DigitalOcean, AWS, Hover, WalkerServers} | +| frequency | Enum | No | The frequency that AnimeThemes is billed by the service {Once, Annually, Biannually, Quarterly, Monthly} | +| usage | Decimal | No | The amount of services consumed by AnimeThemes in the billing period | +| month_to_date_balance | Decimal | No | The balance of the AnimeThemes account with consideration to usage | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/balance/index/README.md b/docs/balance/index/README.md index 67109be..a2aad33 100644 --- a/docs/balance/index/README.md +++ b/docs/balance/index/README.md @@ -50,8 +50,6 @@ GET /api/balance/ ## Response ```json -Status: 200 - { balances: [ { diff --git a/docs/balance/show/README.md b/docs/balance/show/README.md index 6540f1b..cf0de53 100644 --- a/docs/balance/show/README.md +++ b/docs/balance/show/README.md @@ -25,8 +25,6 @@ GET /api/balance/{id} ## Response ```json -Status: 200 - { balance: { id: id, diff --git a/docs/entry/README.md b/docs/entry/README.md index f4e5c59..47e6239 100644 --- a/docs/entry/README.md +++ b/docs/entry/README.md @@ -12,17 +12,17 @@ For example, the Bakemonogatari ED theme has three entries to represent three ve ### Fields -| Name | Type | Description | -| :--------: | :-----: | :-------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| version | Integer | The version number of the theme | -| episodes | String | The URL slug & route key of the resource | -| nsfw | Boolean | Is not safe for work content included? | -| spoiler | Boolean | Is content included that may spoil the viewer? | -| notes | String | Any additional information for this sequence | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :-------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| version | Integer | Yes | The version number of the theme | +| episodes | String | Yes | The URL slug & route key of the resource | +| nsfw | Boolean | No | Is not safe for work content included? | +| spoiler | Boolean | No | Is content included that may spoil the viewer? | +| notes | String | Yes | Any additional information for this sequence | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/entry/index/README.md b/docs/entry/index/README.md index 67956a5..4168f7e 100644 --- a/docs/entry/index/README.md +++ b/docs/entry/index/README.md @@ -50,8 +50,6 @@ GET /api/entry/ ## Response ```json -Status: 200 - { entries: [ { diff --git a/docs/entry/show/README.md b/docs/entry/show/README.md index e631b29..4a36651 100644 --- a/docs/entry/show/README.md +++ b/docs/entry/show/README.md @@ -27,8 +27,6 @@ GET /api/entry/{id} ## Response ```json -Status: 200 - { entry: { id: id, diff --git a/docs/image/README.md b/docs/image/README.md index 4d0d7cc..f4816ab 100644 --- a/docs/image/README.md +++ b/docs/image/README.md @@ -12,17 +12,17 @@ For example, the Bakemonogatari anime has two images to represent small and larg ### Fields -| Name | Type | Description | -| :--------: | :-----: | :------------------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| path | String | The path of the file in storage | -| size | Integer | The size of the file in storage in Bytes | -| mimetype | String | The media type of the file in storage | -| facet | Enum | The component that the resource is intended for {Small Cover, Large Cover} | -| link | String | The URL to stream the file from storage | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :------------------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| path | String | No | The path of the file in storage | +| size | Integer | No | The size of the file in storage in Bytes | +| mimetype | String | No | The media type of the file in storage | +| facet | Enum | Yes | The component that the resource is intended for {Small Cover, Large Cover} | +| link | String | No | The URL to stream the file from storage | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/image/index/README.md b/docs/image/index/README.md index 829138c..76ea9d6 100644 --- a/docs/image/index/README.md +++ b/docs/image/index/README.md @@ -47,8 +47,6 @@ GET /api/image/ ## Response ```json -Status: 200 - { images: [ { diff --git a/docs/image/show/README.md b/docs/image/show/README.md index ec8ee7f..52901a9 100644 --- a/docs/image/show/README.md +++ b/docs/image/show/README.md @@ -27,8 +27,6 @@ GET /api/image/{id} ## Response ```json -Status: 200 - { image: { id: id, diff --git a/docs/jsonapi.md b/docs/jsonapi.md index feae3e6..6b94966 100644 --- a/docs/jsonapi.md +++ b/docs/jsonapi.md @@ -14,13 +14,29 @@ Here we will provide an overview of where the AnimeThemes API adheres to or devi The AnimeThemes API shall favor silent failures to raising exceptions. +```sh +# The anime season filter expects {winter,spring,summer,fall} +# This filter value will be discarded rather than raising an exception +/api/anime?filter[season]=autumn +``` + The AnimeThemes API shall allow case-insensitive matching. +```sh +# Both query strings will match the anime year filter +/api/anime?filter[year]=2000 + +/api/anime?filter[Year]=2000 +``` + ## Content Negotiation -The AnimeThemes API does **NOT** require a `Content-Type` or `Accept` header. +The AnimeThemes API does **NOT** require a `Content-Type` or `Accept` header. AnimeThemes filters API requests and sets the `Accept` header on behalf of the client. -AnimeThemes filters API requests and sets the `Accept` header on behalf of the client. +```sh +# A simple curl request can be made without specifying headers. +curl https://staging.animethemes.moe/api/anime +``` ## Document Structure @@ -28,94 +44,444 @@ AnimeThemes filters API requests and sets the `Accept` header on behalf of the c The AnimeThemes API specifies a custom `data` wrap for top-level members. +```json +// The anime show endpoint uses the custom data wrap 'anime'. +{ + anime: { + ... + } +} +``` + ### Resource Objects -The AnimeThemes API Resource Objects do **NOT** contain top-level members `id` and `type`. +The AnimeThemes API Resource Objects do **NOT** contain top-level member `type`. + +```json +// Types are hinted by their custom data wrapper +{ + anime: { + ... + } +} +``` The AnimeThemes API Resource Object attributes are included as top-level members and are **NOT** contained in an `attributes` object. -The AnimeThemes API Resource Objects relationships are included as nested members and are **NOT** contained in an `relationships` object. +```json +// The show anime endpoint includes attributes as top-level members +{ + anime: { + id: id, + name: "name", + slug: "slug", + year: year, + season: "season", + synopsis: "synopsis", + ... + } +} +``` + +The AnimeThemes API Resource Objects relationships are included as top-level members and are **NOT** contained in a `relationships` object. + +```json +// The show anime endpoint includes relationships as top-level members +{ + anime: { + ... + synonyms: [ + ... + ], + themes: [ + ... + ], + series: [ + ... + ], + resources: [ + ... + ], + images: [ + ... + ], + } +} +``` The AnimeThemes API Resource Object collections shall contain `links` and `meta` members for pagination strategies. +```json +// The anime index endpoint contains links and meta members +{ + anime: [ + { + id: id, + name: "name", + slug: "slug", + year: year, + season: "season", + synopsis: "synopsis", + created_at: "created_at", + updated_at: "updated_at", + deleted_at: "deleted_at" + }, + ... + ], + links: { + first: "first", + last: "last", + prev: "prev", + next: "next" + }, + meta: { + current_page: current_page, + from: from, + path: "path", + per_page: per_page, + to: to + } +} +``` + ## Fetching Data ### Fetching Resources & Relationships The AnimeThemes API does **NOT** support fetching resources or relationships. +```json +// The show anime endpoint relationships can be fetched directly +{ + anime: { + ... + synonyms: [ + ... + ], + themes: [ + ... + ], + series: [ + ... + ], + resources: [ + ... + ], + images: [ + ... + ], + } +} +``` + ### Inclusion of Related Resources -The AnimeThemes API supports inclusion of related resources for every endpoint. +The AnimeThemes API supports inclusion of related resources for every endpoint unless otherwise specified. + +```json +// /api/anime/{slug}?include=themes,series +{ + anime: { + ... + themes: [ + ... + ], + series: [ + ... + ], + } +} +``` For endpoints that produce responses of mixed typed top-level members, inclusion of related resources are scoped by type `include[type]`. +```json +// /api/search?q={query}&include[anime]=resources +{ + search: { + anime: [ + { + ... + resources: [ + ... + ], + }, + ... + ], + ... + } +} +``` + If inclusion of related resources is not specified, the AnimeThemes API shall **NOT** include any related resources. +```json +// /api/anime/{slug} +// No relationships are included by default +{ + anime: { + id: id, + name: "name", + slug: "slug", + year: year, + season: "season", + synopsis: "synopsis", + created_at: "created_at", + updated_at: "updated_at", + deleted_at: "deleted_at" + } +} +``` + ### Sparse Fieldsets -The AnimeThemes API supports sparse fieldsets for every endpoint. +The AnimeThemes API supports sparse fieldsets for every endpoint unless otherwise specified. + +```json +// /api/anime/{slug}?fields[anime]=name,year +{ + anime: { + name: "name", + year: year + } +} +``` If the client does not specify the set of fields for a given resource type, the AnimeThemes API shall send all fields. +```json +// /api/anime/{slug} +{ + anime: { + id: id, + name: "name", + slug: "slug", + year: year, + season: "season", + synopsis: "synopsis", + created_at: "created_at", + updated_at: "updated_at", + deleted_at: "deleted_at" + } +} +``` + ### Sorting The AnimeThemes API supports sorting for every endpoint that returns a collection of resources. +```json +// /api/anime?sort=year +{ + anime: [ + { + id: id, + name: "name", + slug: "slug", + year: 1963, + season: "season", + synopsis: "synopsis", + created_at: "created_at", + updated_at: "updated_at", + deleted_at: "deleted_at" + }, + ... + ], + links: { + first: "first", + last: "last", + prev: "prev", + next: "next" + }, + meta: { + current_page: current_page, + from: from, + path: "path", + per_page: per_page, + to: to + } +} +``` + ### Pagination -The AnimeThemes API supports an offset pagination strategy for every endpoint that returns a collection of resources. +The AnimeThemes API supports an offset pagination strategy for every endpoint that returns a collection of resources. For these endpoints, the AnimeThemes API supports the `page[number]` and `page[size]` query parameters. -For these endpoints, the AnimeThemes API supports the `page[number]` and `page[size]` query parameters. +```json +// /api/anime?page[number]=2&page[size]=15 +{ + anime: [ + { + id: id, + name: "name", + slug: "slug", + year: year, + season: "season", + synopsis: "synopsis", + created_at: "created_at", + updated_at: "updated_at", + deleted_at: "deleted_at" + }, + ... + ], + links: { + first: "first", + last: "last", + prev: "prev", + next: "next" + }, + meta: { + current_page: 2, + from: 16, + path: "path", + per_page: 15, + to: 30 + } +} +``` -For endpoints that produce responses of mixed typed top-level members, the AnimeThemes.moe supports a limit pagination strategy. +For endpoints that produce responses of mixed typed top-level members, the AnimeThemes.moe supports a limit pagination strategy. For these endpoints, the AnimeThemes API support the `limit` query parameter. -For these endpoints, the AnimeThemes API support the `limit` query parameter. +```json +// /api/search?q={query}&limit=1 +{ + search: { + anime: [ + { + ... + resources: [ + ... + ], + } + ], + ... + } +} +``` ### Filtering -The AnimeThemes API supports filtering for every endpoint. +The AnimeThemes API supports filtering for every endpoint unless otherwise specified. + +```sh +# The show anime endpoint allows filtering on the year attribute, for example +/api/anime?filter[year]=2000 +``` **Strategy** -The AnimeThemes API supports the [**recommended**](https://jsonapi.org/recommendations/#filtering) base strategy for filtering. +The AnimeThemes API supports the [**recommended**](https://jsonapi.org/recommendations/#filtering) base strategy for filtering with the following extended syntax: -The AnimeThemes API extended syntax is `filter[scope][field][comparison operator][logical operator]=value(s)`. +```sh +filter[scope][field][comparison operator][logical operator]=value(s) +``` **Scope** The AnimeThemes API supports scoping filters by resource type. +```sh +# This will match the created_at filter for anime resources and will not apply the filter for other types +/api/anime?filter[anime][created_at]=2021-01-01 +``` + If a scope is not provided, the filter shall match all types. -**Field** - -The AnimeThemes API supports filtering against resource attributes. +```sh +# This will match the created_at filter for all types +/api/anime?filter[created_at]=2021-01-01 +``` **Comparison Operator** The AnimeThemes API supports the following comparison operators for filter conditions: -* EQ -* NE -* LT -* GT -* LTE -* GTE +EQ + +```sh +# This will match anime of year 2000 +/api/anime?filter[year][eq]=2000 +``` + +NE + +```sh +# This will match anime not of year 2000 +/api/anime?filter[year][ne]=2000 +``` + +LT + +```sh +# This will match anime where the year is less than 2000 +/api/anime?filter[year][lt]=2000 +``` + +GT + +```sh +# This will match anime where the year is greater than 2000 +/api/anime?filter[year][gt]=2000 +``` + +LTE + +```sh +# This will match anime where the year is less than or equal to 2000 +/api/anime?filter[year][lte]=2000 +``` + +GTE + +```sh +# This will match anime where the year is greater than 2000 +/api/anime?filter[year][gte]=2000 +``` If a comparison operator is not provided, the filter shall use the EQ operator. +```sh +# This will match anime of year 2000 +/api/anime?filter[year]=2000 +``` + **Logical Operators** The AnimeThemes API supports the following logical operators: -* AND -* OR +AND + +```sh +# This will match anime where the year is greater than 2000 and less than 2010 +/api/anime?filter[year][gt][and]=2000&filter[year][lt][and]=2010 +``` + +OR + +```sh +# This will match anime where the year is less than 2000 or greater than 2010 +/api/anime?filter[year][lt][or]=2000&filter[year][gt][or]=2010 +``` If a logical operator is not provided, the filter shall use the AND operator. +```sh +# This will match anime where the year is greater than 2000 and less than 2010 +/api/anime?filter[year][gt]=2000&filter[year][lt]=2010 +``` + The AnimeThemes API supports the following logical operator for multi-value filter conditions: -* NOT +NOT -If the multi-value logical operator is not specified, the filter shall exclude the multi-value logical operator. \ No newline at end of file +```sh +# This will match anime where the year is not in {2000,2001,2002} +/api/anime?filter[year][not]=2000,2001,2002 +``` + +If the multi-value logical operator is not specified, the filter shall exclude the multi-value logical operator. + +```sh +# This will match anime where the year is in {2000,2001,2002} +/api/anime?filter[year]=2000,2001,2002 +``` \ No newline at end of file diff --git a/docs/ratelimiting.md b/docs/ratelimiting.md new file mode 100644 index 0000000..7467ed0 --- /dev/null +++ b/docs/ratelimiting.md @@ -0,0 +1,51 @@ +--- +title: Rate Limiting +--- + +# Rate Limiting + +--- + +The AnimeThemes API applies the standard named rate limiter of the Laravel Framework. + +Here we will provide an overview of managing request quotas. + +## Response Headers + +The AnimeThemes API limits requests to 60 per minute. + +The AnimeThemes API will return `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers in the response. + +```sh +... +X-RateLimit-Limit: 60 +X-RateLimit-Remaining: 59 +... +``` + +If the rate limit is exceeded, the AnimeThemes API will return `Retry-After` and `X-RateLimit-Reset` headers in the response. + +```sh +... +X-RateLimit-Limit: 60 +X-RateLimit-Remaining: 0 +Retry-After: 60 +X-RateLimit-Reset: 1625073463180 +... +``` + +```json +{ + errors: [ + { + status: "429", + code: "1", + title: "throttle_requests_exception", + detail: "ThrottleRequestsException", + source: { + pointer: "" + } + } + ] +} +``` \ No newline at end of file diff --git a/docs/resource/README.md b/docs/resource/README.md index 06dcf52..9e4a11e 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -12,16 +12,16 @@ For example, the Bakemonogatari anime has MyAnimeList, AniList and AniDB resourc ### Fields -| Name | Type | Description | -| :---------: | :-----: | :------------------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| link | String | The URL of the external site | -| external_id | Integer | The primary key of the resource in the external site | -| site | Enum | The external site that the resource belongs to {Official Website, Twitter, AniDB, Anilist, Anime-Planet, Anime News Network, Kitsu, MyAnimeList, Wikipedia} | -| as | String | Used to distinguish resources that map to the same artist or anime | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :---------: | :-----: | :------: | :------------------------------------------------------------------| +| id | Integer | No | The primary key of the resource | +| link | String | Yes | The URL of the external site | +| external_id | Integer | Yes | The primary key of the resource in the external site | +| site | Enum | Yes | The external site that the resource belongs to {Official Website, Twitter, AniDB, Anilist, Anime-Planet, Anime News Network, Kitsu, MyAnimeList, Wikipedia} | +| as | String | Yes | Used to distinguish resources that map to the same artist or anime | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/resource/index/README.md b/docs/resource/index/README.md index abe5c27..841e2b2 100644 --- a/docs/resource/index/README.md +++ b/docs/resource/index/README.md @@ -46,8 +46,6 @@ GET /api/resource/ ## Response ```json -Status: 200 - { resources: [ { diff --git a/docs/resource/show/README.md b/docs/resource/show/README.md index 43a9934..39b2842 100644 --- a/docs/resource/show/README.md +++ b/docs/resource/show/README.md @@ -27,8 +27,6 @@ GET /api/resource/{id} ## Response ```json -Status: 200 - { resource: { id: id, diff --git a/docs/search/README.md b/docs/search/README.md index ec6426c..8b5d11a 100644 --- a/docs/search/README.md +++ b/docs/search/README.md @@ -27,8 +27,6 @@ GET /api/search/ ## Response ```json -Status: 200 - { search: { anime: [ diff --git a/docs/series/README.md b/docs/series/README.md index 1c53cf8..2ced7a7 100644 --- a/docs/series/README.md +++ b/docs/series/README.md @@ -12,14 +12,14 @@ For example, the Monogatari series is the collection of the Bakemonogatari anime ### Fields -| Name | Type | Description | -| :--------: | :-----: | :-------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| name | String | The primary title of the series | -| slug | String | The URL slug & route key of the resource | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| name | String | No | The primary title of the series | +| slug | String | No | The URL slug & route key of the resource | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/series/index/README.md b/docs/series/index/README.md index fd8568b..1d84640 100644 --- a/docs/series/index/README.md +++ b/docs/series/index/README.md @@ -45,8 +45,6 @@ GET /api/series/ ## Response ```json -Status: 200 - { series: [ { diff --git a/docs/series/show/README.md b/docs/series/show/README.md index 4de1dcb..806c8b8 100644 --- a/docs/series/show/README.md +++ b/docs/series/show/README.md @@ -27,8 +27,6 @@ GET /api/series/{slug} ## Response ```json -Status: 200 - { series: { id: id, diff --git a/docs/song/README.md b/docs/song/README.md index f94f37d..768d2c2 100644 --- a/docs/song/README.md +++ b/docs/song/README.md @@ -12,14 +12,14 @@ For example, Staple Stable is the song for the Bakemonogatari OP1 theme. ### Fields -| Name | Type | Description | -| :--------: | :-----: | :-------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| title | String | The name of the composition | -| as | String | Used to distinguish a performance by alias, character or group | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| title | String | Yes | The name of the composition | +| as | String | Yes | Used to distinguish a performance by alias, character or group | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/song/index/README.md b/docs/song/index/README.md index c10142f..08c5009 100644 --- a/docs/song/index/README.md +++ b/docs/song/index/README.md @@ -44,8 +44,6 @@ GET /api/song/ ## Response ```json -Status: 200 - { songs: [ { diff --git a/docs/song/show/README.md b/docs/song/show/README.md index afe4758..699622a 100644 --- a/docs/song/show/README.md +++ b/docs/song/show/README.md @@ -27,8 +27,6 @@ GET /api/song/{id} ## Response ```json -Status: 200 - { song: { id: id, diff --git a/docs/synonym/README.md b/docs/synonym/README.md index 56c4286..70d66c2 100644 --- a/docs/synonym/README.md +++ b/docs/synonym/README.md @@ -12,13 +12,13 @@ For example, the anime Bakemonogatari has the synonym "Ghostory". ### Fields -| Name | Type | Description | -| :--------: | :-----: | :-------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| text | String | The alternate title or common abbreviations | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| text | String | Yes | The alternate title or common abbreviations | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/synonym/index/README.md b/docs/synonym/index/README.md index 81d2f98..977404e 100644 --- a/docs/synonym/index/README.md +++ b/docs/synonym/index/README.md @@ -45,8 +45,6 @@ GET /api/synonym/ ## Response ```json -Status: 200 - { synonyms: [ { diff --git a/docs/synonym/show/README.md b/docs/synonym/show/README.md index 3a57ce1..1a83987 100644 --- a/docs/synonym/show/README.md +++ b/docs/synonym/show/README.md @@ -27,8 +27,6 @@ GET /api/synonym/{id} ## Response ```json -Status: 200 - { synonym: { id: id, diff --git a/docs/theme/README.md b/docs/theme/README.md index c544475..ef00666 100644 --- a/docs/theme/README.md +++ b/docs/theme/README.md @@ -12,16 +12,16 @@ For example, the anime Bakemonogatari has five OP themes and one ED theme. ### Fields -| Name | Type | Description | -| :--------: | :-----: | :--------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| type | Enum | The type of the sequence {OP, ED} | -| sequence | Integer | The numeric ordering of the theme | -| group | String | Used to distinguish sequence belongs to dubs, rebroadcasts, etc. | -| slug | String | The URL slug & route key of the resource | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :--------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| type | Enum | Yes | The type of the sequence {OP, ED} | +| sequence | Integer | Yes | The numeric ordering of the theme | +| group | String | Yes | Used to distinguish sequence belongs to dubs, rebroadcasts, etc. | +| slug | String | No | The URL slug & route key of the resource | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/theme/index/README.md b/docs/theme/index/README.md index d6e79da..c17d843 100644 --- a/docs/theme/index/README.md +++ b/docs/theme/index/README.md @@ -52,8 +52,6 @@ GET /api/theme/ ## Response ```json -Status: 200 - { themes: [ { diff --git a/docs/theme/show/README.md b/docs/theme/show/README.md index 92beb9f..9abfe9e 100644 --- a/docs/theme/show/README.md +++ b/docs/theme/show/README.md @@ -27,8 +27,6 @@ GET /api/theme/{id} ## Response ```json -Status: 200 - { theme: { id: id, diff --git a/docs/transaction/README.md b/docs/transaction/README.md index 1e6ef76..ad33dc9 100644 --- a/docs/transaction/README.md +++ b/docs/transaction/README.md @@ -10,17 +10,17 @@ A transaction API resource represents an invoice from or a payment to a billing ### Fields -| Name | Type | Description | -| :-------------------: | :-----: | :--------------------------------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| date | Date | The date that the transaction was made | -| service | Enum | The service that is billing AnimeThemes {Other, DigitalOcean, AWS, Hover, WalkerServers} | -| description | String | The short description of what the transaction is for | -| amount | Decimal | The amount of the transaction billed by or paid to the billing service by AnimeThemes | -| external_id | Integer | The identifier used by the service for the transaction, if applicable | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :-------------------: | :-----: | :------: | :--------------------------------------------------------------------------------------- | +| id | Integer | No | The primary key of the resource | +| date | Date | No | The date that the transaction was made | +| service | Enum | No | The service that is billing AnimeThemes {Other, DigitalOcean, AWS, Hover, WalkerServers} | +| description | String | No | The short description of what the transaction is for | +| amount | Decimal | No | The amount of the transaction billed by or paid to the billing service by AnimeThemes | +| external_id | Integer | Yes | The identifier used by the service for the transaction, if applicable | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/transaction/index/README.md b/docs/transaction/index/README.md index 13530b1..dea2ae7 100644 --- a/docs/transaction/index/README.md +++ b/docs/transaction/index/README.md @@ -49,8 +49,6 @@ GET /api/transaction/ ## Response ```json -Status: 200 - { transactions: [ { diff --git a/docs/transaction/show/README.md b/docs/transaction/show/README.md index 17d36e7..bcb19cb 100644 --- a/docs/transaction/show/README.md +++ b/docs/transaction/show/README.md @@ -25,8 +25,6 @@ GET /api/transaction/{id} ## Response ```json -Status: 200 - { transaction: { id: id, diff --git a/docs/video/README.md b/docs/video/README.md index bcf3bd6..c6477d8 100644 --- a/docs/video/README.md +++ b/docs/video/README.md @@ -12,26 +12,26 @@ For example, the video Bakemonogatari-OP1.webm represents the WebM of the Bakemo ### Fields -| Name | Type | Description | -| :--------: | :-----: | :------------------------------------------------------------------------- | -| id | Integer | The primary key of the resource | -| basename | String | The basename of the file in storage | -| filename | String | The filename of the file in storage | -| path | String | The path of the file in storage | -| size | Integer | The size of the file in storage in Bytes | -| mimetype | String | The media type of the file in storage | -| resolution | Integer | The frame height of the file in storage | -| nc | Boolean | Is the video creditless? | -| subbed | Boolean | Does the video include subtitles of dialogue? | -| lyrics | Boolean | Does the video include subtitles of song lyrics? | -| uncen | Boolean | Is the video an uncensored version of a censored sequence? | -| source | Enum | Where did this video come from? {WEB, RAW, BD, DVD, VHS, LD} | -| overlap | Enum | The degree to which the sequence and episode content overlap {None, Transition, Over} | -| tags | String | The attributes used to distinguish the file within the context of a theme | -| link | String | The URL to stream the file from storage | -| created_at | Date | The date that the resource was created | -| updated_at | Date | The date that the resource was last modified | -| deleted_at | Date | The date that the resource was deleted | +| Name | Type | Nullable | Description | +| :--------: | :-----: | :------: | :------------------------------------------------------------------------------------ | +| id | Integer | No | The primary key of the resource | +| basename | String | No | The basename of the file in storage | +| filename | String | No | The filename of the file in storage | +| path | String | No | The path of the file in storage | +| size | Integer | No | The size of the file in storage in Bytes | +| mimetype | String | No | The media type of the file in storage | +| resolution | Integer | Yes | The frame height of the file in storage | +| nc | Boolean | No | Is the video creditless? | +| subbed | Boolean | No | Does the video include subtitles of dialogue? | +| lyrics | Boolean | No | Does the video include subtitles of song lyrics? | +| uncen | Boolean | No | Is the video an uncensored version of a censored sequence? | +| source | Enum | Yes | Where did this video come from? {WEB, RAW, BD, DVD, VHS, LD} | +| overlap | Enum | No | The degree to which the sequence and episode content overlap {None, Transition, Over} | +| tags | String | No | The attributes used to distinguish the file within the context of a theme | +| link | String | No | The URL to stream the file from storage | +| created_at | Date | No | The date that the resource was created | +| updated_at | Date | No | The date that the resource was last modified | +| deleted_at | Date | Yes | The date that the resource was deleted | ### Allowed Include Paths diff --git a/docs/video/index/README.md b/docs/video/index/README.md index 9b5e001..86b55bc 100644 --- a/docs/video/index/README.md +++ b/docs/video/index/README.md @@ -62,8 +62,6 @@ GET /api/video/ ## Response ```json -Status: 200 - { videos: [ { diff --git a/docs/video/show/README.md b/docs/video/show/README.md index bea33e6..30a41e0 100644 --- a/docs/video/show/README.md +++ b/docs/video/show/README.md @@ -27,8 +27,6 @@ GET /api/video/{basename} ## Response ```json -Status: 200 - { video: { id: id, diff --git a/docs/year/index/README.md b/docs/year/index/README.md index 60b616d..8deae9a 100644 --- a/docs/year/index/README.md +++ b/docs/year/index/README.md @@ -21,8 +21,6 @@ None ## Response ```json -Status: 200 - [ 1963, 1964, diff --git a/docs/year/show/README.md b/docs/year/show/README.md index f80f4d1..f37c6b8 100644 --- a/docs/year/show/README.md +++ b/docs/year/show/README.md @@ -27,8 +27,6 @@ GET /api/year/{year} ## Response ```json -Status: 200 - { winter: [ { diff --git a/package-lock.json b/package-lock.json index 2b8a35f..63d1e34 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,6 +8,7 @@ "version": "0.0.1", "license": "MIT", "dependencies": { + "dotenv": "^8.6.0", "vuepress-theme-api": "^1.0.1" }, "devDependencies": { @@ -15367,6 +15368,7 @@ "integrity": "sha512-pM7CR3yXB6L8Gfn6EmX7FLNE3+V/15I3o33GkSNsWvgsMp6HVGXKkXgojrcfUUauyL1LZOdvTmu4enU2RePGHw==", "dev": true, "requires": { + "@babel/core": "^7.11.0", "@babel/helper-compilation-targets": "^7.9.6", "@babel/helper-module-imports": "^7.8.3", "@babel/plugin-proposal-class-properties": "^7.8.3", @@ -15379,6 +15381,7 @@ "@vue/babel-plugin-jsx": "^1.0.3", "@vue/babel-preset-jsx": "^1.2.4", "babel-plugin-dynamic-import-node": "^2.3.3", + "core-js": "^3.6.5", "core-js-compat": "^3.6.5", "semver": "^6.1.0" } diff --git a/package.json b/package.json index 4150cce..994c9cd 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "vuepress": "^1.5.3" }, "dependencies": { + "dotenv": "^8.6.0", "vuepress-theme-api": "^1.0.1" } }