mirror of
https://github.com/jikan-me/jikan-rest.git
synced 2025-02-20 11:23:35 +08:00
update docs
This commit is contained in:
Irfan
parent
4bc0cf020e
commit
7a62b748d3
@ -23,10 +23,113 @@ class Controller extends BaseController
|
||||
* @OA\Info(
|
||||
* version="4.0.0",
|
||||
* title="Jikan API",
|
||||
* description="[Jikan](https://jikan.moe) is an **Unofficial** MyAnimeList API. It scrapes the website to satisfy the need for a complete API - which MyAnimeList lacks.",
|
||||
* description="
|
||||
*
|
||||
* ## Information
|
||||
*
|
||||
* [Jikan](https://jikan.moe) is an **Unofficial** MyAnimeList API. It scrapes the website to satisfy the need for a complete API - which MyAnimeList lacks.
|
||||
*
|
||||
* ⚡ Jikan is powered by it's awesome backers - 🙏 [Become a backer](https://www.patreon.com/jikan)
|
||||
*
|
||||
* ### Rate Limiting
|
||||
*
|
||||
* | Duration | Requests |
|
||||
* |----|----|
|
||||
* | Daily | **Unlimited** |
|
||||
* | Per Minute | 60 requests |
|
||||
* | Per Second | 3 requests |
|
||||
*
|
||||
*
|
||||
* ### JSON Notes
|
||||
* - Any property (except arrays or objects) whose value does not exist or is undetermined, will be `null`.
|
||||
* - Any array or object property whose value does not exist or is undetermined, will be `null`.
|
||||
* - Any `score` property whose value does not exist or is undetermined, will be `0`.
|
||||
* - All dates and timestamps are returned in [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format and in UTC timezone
|
||||
*
|
||||
* ### Caching
|
||||
* By **CACHING**, we refer to the data parsed from MyAnimeList which is stored temporarily on our servers to provide better API performance.
|
||||
*
|
||||
* All requests, by default are cached for **24 hours** except the following endpoints which have their own unique cache **Time To Live**.
|
||||
*
|
||||
* | Request | TTL |
|
||||
* | ---- | ---- |
|
||||
* | All (Default) | 24 hours |
|
||||
* | User Anime/Manga List | 5 minutes |
|
||||
*
|
||||
*
|
||||
* The following response headers will detail cache information.
|
||||
*
|
||||
* | Header | Remarks |
|
||||
* | ---- | ---- |
|
||||
* | `Expires` | Expiry unix timestamp |
|
||||
*
|
||||
*
|
||||
* ### Allowed HTTP(s) requests
|
||||
*
|
||||
* **Jikan REST API does not provide authenticated requests for MyAnimeList.** This means you can not use it to update your anime/manga list.
|
||||
* Only GET requests are supported which return READ-ONLY data.
|
||||
*
|
||||
* ### HTTP Responses
|
||||
*
|
||||
* | HTTP Status | Remarks |
|
||||
* | ---- | ---- |
|
||||
* | `200 - OK` | The request was successful |
|
||||
* | `304 - Not Modified` | You have the latest data (Cache Validation response) |
|
||||
* | `400 - Bad Request` | You've made an invalid request. Recheck documentation |
|
||||
* | `404 - Not Found` | The resource was not found or MyAnimeList responded with a `404` |
|
||||
* | `405 - Method Not Allowed` | Requested Method is not supported for resource. Only `GET` requests are allowed |
|
||||
* | `429 - Too Many Request` | You are being rate limited by Jikan or MyAnimeList is rate-limiting our servers (specified in the error response) |
|
||||
* | `500 - Internal Server Error` | Something is not working on our end. If you see an error response with a `report_url` URL, please click on it to open an auto-generated GitHub issue |
|
||||
* | `503 - Service Unavailable` | The service has broke. |
|
||||
*
|
||||
*
|
||||
* ### JSON Error Response
|
||||
*
|
||||
* ```json
|
||||
* {
|
||||
* 'status': 404,
|
||||
* 'type': 'BadResponseException',
|
||||
* 'message': 'Resource does not exist',
|
||||
* 'error': 'Something Happened',
|
||||
* 'report_url': 'https://github.com...'
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* | Property | Remarks |
|
||||
* | ---- | ---- |
|
||||
* | `status` | Returned HTTP Status Code |
|
||||
* | `type` | `Exception` generated from the API |
|
||||
* | `message` | Human-readable error message |
|
||||
* | `error` | Error response and trace from the API |
|
||||
* | `report_url` | Clicking this would redirect you to a generated GitHub issue. ℹ It's only returned on a parser error. |
|
||||
*
|
||||
*
|
||||
* ### Cache Validation
|
||||
*
|
||||
* - All requests return a `ETag` header which is an MD5 hash of the response
|
||||
* - You can use this hash to verify if there's new or updated content by suppliying it as the value for the `If-None-Match` in your next request header
|
||||
* - You will get a HTTP `304 - Not Modified` response if the content has not changed
|
||||
* - If the content has changed, you'll get a HTTP `200 - OK` response with the updated JSON response
|
||||
*
|
||||
* 
|
||||
*
|
||||
* ### Disclaimer
|
||||
*
|
||||
* - Jikan is not affiliated with MyAnimeList.net.
|
||||
* - Jikan is a free, open-source API. Please use it responsibly.
|
||||
*
|
||||
* ----
|
||||
*
|
||||
* By using the API, you are agreeing to Jikan's [terms of use](https://jikan.moe/terms) policy.
|
||||
*
|
||||
* [v3 Documentation](https://jikan.docs.apiary.io/) - [Wrappers/SDKs](https://github.com/jikan-me/jikan#wrappers) - [Report an issue](https://github.com/jikan-me/jikan-rest/issues/new)
|
||||
* [Host your own server](https://github.com/jikan-me/jikan-rest)
|
||||
* ",
|
||||
* termsOfService="https://jikan.moe/terms",
|
||||
*
|
||||
* @OA\Contact(
|
||||
* email="neko@jikan.moe"
|
||||
* name="API Support (Discord)",
|
||||
* url="http://discord.jikan.moe"
|
||||
* ),
|
||||
* @OA\License(
|
||||
* name="MIT",
|
||||
@ -35,12 +138,12 @@ class Controller extends BaseController
|
||||
* ),
|
||||
* @OA\Server(
|
||||
* description="Jikan REST API Beta",
|
||||
* url="https://api.jikan.moe/v4"
|
||||
* url="https://api.jikan.moe/v4",
|
||||
* ),
|
||||
* @OA\ExternalDocumentation(
|
||||
* description="Find out more about Jikan",
|
||||
* description="About",
|
||||
* url="https://jikan.moe"
|
||||
* )
|
||||
* ),
|
||||
* )
|
||||
*/
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
Loading…
x
Reference in New Issue
Block a user