MangaBaka
Sign in
Discord Join our cozy Discord community to chat with like-minded people and stay up to date with MangaBaka (and get the BAKA server tag)

Response headers

How the data and the API work, and why.

The headers the API sets on its responses, what they mean, and which ones are worth reading in a client.

Summary#↑

Header When Example
X-Request-ID Responses from the API 9d90dbab-6e6e-4527-9aa9-919846fdb64b
X-API-Version Versioned endpoints v1
X-API-Stability Versioned endpoints stable
Cache-Control 200 responses public, max-age=60
CDN-Cache-Control 200 responses public, max-age=604800, stale-while-revalidate=60
cf-cache-status Every response HIT
Link Responses from the API <https://mangabaka.org/api.json>; rel="service-desc"; ...
Access-Control-Allow-Origin Every response, errors included *
Retry-After 429 from the rate limiter 10

X-Request-ID#↑

A random UUID generated by the server for each request. A value you send in your own X-Request-ID header is ignored, not echoed.

Include it when you report a problem. A response served from cache carries the ID of the request that filled the cache, not yours.

X-API-Version and X-API-Stability#↑

The version from the path, and the stability of the endpoint that answered: stable, beta, deprecated or internal. Stability is per endpoint, so two calls under /v1 can return different values. See versioning and stability.

Cache-Control and CDN-Cache-Control#↑

CDN-Cache-Control is how long our CDN keeps the response. Cache-Control is how long your browser or HTTP client may keep it, at most 60 seconds, so corrections reach you quickly.

  • stale-while-revalidate=60 lets the CDN serve an expired copy for up to 60 seconds while it fetches a fresh one.
  • Endpoints that are not cached, including everything under /my, send Cache-Control: private, no-store and CDN-Cache-Control: no-store.
  • Only 200 responses carry these headers. Errors are never cached.

The cache time for each endpoint is in its API reference entry. Why caching matters for your rate limit: rate limits and caching.

cf-cache-status#↑

Set by the CDN.

Value Meaning
HIT Served from cache. Does not count toward your rate limit.
MISS Not in cache. Fetched from the API and stored.
UPDATING An expired copy, served while a fresh one is fetched.
BYPASS The response is not cacheable, for example an error.

On a HIT, the Age header says how many seconds the copy has been cached.

Points at the machine-readable descriptions of the API:

rel Target
service-desc The OpenAPI spec, https://mangabaka.org/api.json
service-doc These docs, https://mangabaka.org/developers
api-catalog https://mangabaka.org/.well-known/api-catalog

CORS#↑

Every response, errors and rate-limit responses included, sends Access-Control-Allow-Origin: *, so browser apps on any origin can call the API.

Preflight OPTIONS requests get a 204 that allows any request header and may be cached for a day (Access-Control-Max-Age: 86400). Under /my, the preflight also allows GET, POST, PUT, PATCH and DELETE.

Every response also sends Access-Control-Expose-Headers: *, so browser code can read all the headers above, X-Request-ID included.