Overview

Our API is exposed as an HTTP/1 and HTTP/2 service over SSL. All endpoints live under the URL https://genkan.io/api/v1 and then generally follow the REST architecture.

Current Version

By default, all requests to https://genkan.io/api/v1 receive the v1 version of the REST API.

We try to avoid breaking backwards-compatibility as much as possible.

Headers

All requests must be encoded as JSON with the Accept: application/json header. Most responses, including errors, are encoded exclusively as JSON as well.

Accept: application/json

Authentication

Provide your API token as part of the Authorization header.

If the authentication is unsuccessful, the status code 401 is returned.

Authorization: Bearer $TOKEN

After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with 403 Forbidden.

HTTP Verbs

Where possible, API strives to use appropriate HTTP verbs for each action.

Verb	Description
GET	Used for retrieving resources.

Pagination

Requests that return multiple items will be paginated to 24 items by default. You can customise this using the query parameters below.

Name	Type	Description	Required
page	integer	Jump to a specific page.	➖
per_page	integer	Set the number of results you want on each page (1 - 120).	➖

Warning

• All paginated endpoints support the page query parameter.
• Not all paginated endpoints support the per_page query parameter.

curl 'https://genkan.io/api/v1/manga?page=2&per_page=60'

Rate Limiting

We limit the number of calls you can make over a certain period of time. Rate limits vary and are specified by the following header in all responses:

Header Name	Description
X-RateLimit-Limit	The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.

If you exceed the rate limit, an error response returns with the status 429 Too Many Requests.

Status: 429 Too Many Requests

Image Proxy

Some endpoints may return two different image properties, such as a thumbnail. We use an image proxy to alter the image and reduce bandwidth usage. This is intended to return a WebP image with 100% quality, however the quality depends on the currently authenticated user as it is defined based on the Data Saver option within the user settings.

If you need to use the images, we would prefer you to use the proxy_* parameter if at all possible.

If you need the raw image you can alternatively the non-proxied image that goes through our CDN.

{
    "thumbnail_url": "https:\/\/cdn.genkan.io\/file\/genkan-io\/manga\/c932b0c7-a984-4ab6-8be5-47ea047bd692\/EPFMyb0jOeUgvR32oPLTreUihBF34jfdc96jJMA1.jpg",
    "proxy_thumbnail_url": "https:\/\/images.weserv.nl?h=420&w=320&q=100&t=absolute&errorredirect=https%3A%2F%2Fcdn.genkan.io%2Ffile%2Fgenkan-io%2Fmanga%2Fc932b0c7-a984-4ab6-8be5-47ea047bd692%2FEPFMyb0jOeUgvR32oPLTreUihBF34jfdc96jJMA1.jpg&output=webp&url=ssl%3Acdn.genkan.io%2Ffile%2Fgenkan-io%2Fmanga%2Fc932b0c7-a984-4ab6-8be5-47ea047bd692%2FEPFMyb0jOeUgvR32oPLTreUihBF34jfdc96jJMA1.jpg"
}

Unique Identifiers

On the majority of our records that store media, we have a unique_id property that we use internally to define a file structure instead of just using the id property. This is mainly to prevent bulk scraping using database IDs.

For the most part the unique_id property will be UUID's, early on within the first few days of the sites launch we used the uniqid (opens new window) function to generate these so some records will be different.

When communicating with the API, to fetch specific records for example, you should use the id property and not the unique_id property.

{
    "thumbnail_url": "https:\/\/cdn.genkan.io\/file\/genkan-io\/manga\/c932b0c7-a984-4ab6-8be5-47ea047bd692\/EPFMyb0jOeUgvR32oPLTreUihBF34jfdc96jJMA1.jpg",
    "proxy_thumbnail_url": "https:\/\/images.weserv.nl?h=420&w=320&q=100&t=absolute&errorredirect=https%3A%2F%2Fcdn.genkan.io%2Ffile%2Fgenkan-io%2Fmanga%2Fc932b0c7-a984-4ab6-8be5-47ea047bd692%2FEPFMyb0jOeUgvR32oPLTreUihBF34jfdc96jJMA1.jpg&output=webp&url=ssl%3Acdn.genkan.io%2Ffile%2Fgenkan-io%2Fmanga%2Fc932b0c7-a984-4ab6-8be5-47ea047bd692%2FEPFMyb0jOeUgvR32oPLTreUihBF34jfdc96jJMA1.jpg"
}