Skip to main content

API cache

Kuroco's API cache

Since Kuroco's billing system is usage-based, we recommend setting up a cache if you are using Kuroco for media sites or other applications where a large number of requests are expected. A properly configured cache can improve response performance and reduce costs at the same time.

With Kuroco, you can configure detailed cache settings for each API and endpoint.

Cache setup considerations

Verify your cache usage for each endpoint with the "7-day usage" column on the endpoint list screen.

Image from Gyazo

The values are displayed in the following order:

(API requests) / (Cached API requests) / (Average response size) / (Average execution time)

If the number of cached API requests is much lower than the number of API requests, review your cache settings.

You can also view the number of API requests and cached API requests by month and day on the [Environment] -> [Usage] screen.
For details, see User guide: Usage.

Verifying if an API response is cached

To check if an API response has been cached, verify the following variables in the response header.


Indicates whether the object is a cache hit or a cache miss. It returns HIT in case of a hit, and PASS or MISS in case of a miss.


Number of seconds since the response was cached.


Number of hits on the cached object.

Cache duration settings

To set the cache period for an endpoint, click the corresponding [Update] button in the endpoint list.

Image from Gyazo

In the configuration dialog, enter the cache duration (in seconds) next to "Cache".

Image from Gyazo

Click [Update] when you are done.

Image from Gyazo

We recommend a cache duration of one day or one week.
Note that endpoints for adding, updating, or deleting data do not have cache settings in their configuration dialog.

The maximum value is 1 year (31557600 seconds).

Stale-While-Revalidate / Stale-If-Error

Kuroco can be configured to improve the efficiency of cache fetching and to reuse the cache in case of errors.
With Stale-While-Revalidate, the cache is held for a set number of seconds after the cache becomes invalid, and the old cache continues to be returned until a new cache is set. This reduces load and unneeded accesses when clearing the cache.
With Stale-If-Error, the cache is held for a set number of seconds after the cache becomes invalid, and the old cache is returned instead, if the origin returns an error. This allows you to construct API responses that are less prone to errors.

Cache clearing

A cache is automatically cleared upon updating the data to be retrieved (such as contents or members).
However, you can also force a cache clearing using the method below.

By endpoint

Click [Clear cache] for the target endpoint in the endpoint list.

Image from Gyazo


Note that this button is only displayed if you have set a cache duration for the endpoint.


To clear the cache of all the endpoints of an API, click [Clear cache] at the top of the endpoint list screen.

Image from Gyazo

Cache units

Even for the same URL, the response object may differ according to the client's environment. In such cases, the server would maintain multiple caches.
For example, a gzip-compressed response would be returned to a client that supports HTTP compression, while a client that does not support HTTP compression would received an uncompressed response. HTTP compression support on the client side is determined by the Accept-Encoding header, and the server side maintains separate caches based on the Accept-Encoding value.

The Vary response header indicates the request headers that Kuroco refers to for cache separation.
For example, if vary: Host, Accept-Encoding, Accept, Origin, Kuroco would maintain a cache for each of the following request headers:

  • Host
  • Accept-Encoding
  • Accept
  • Origin

Kuroco also references the following request headers based on the API security settings.

Token authentication

When static or dynamic tokens are used for authentication, X-RCMS-API-ACCESS-TOKEN will be added to the the Vary response header.
In other words, a common cache is generated for all clients in the same environment when using static tokens, whereas a separate cache is generated for each user when using dynamic tokens.

When cookie authentication is selected, User-Agent and Cookie will be added to the Vary response header.
(Note: Cookie will not be added to the header when the user agent is a bot.)

IP address restrictions on APIs

Regardless of security settings, if you have set IP address restrictions for an API, a separate cache will be generated for each client IP address.

Image from Gyazo

IP address restrictions to the admin panel

If you have set IP restrictions to the admin panel, a separate cache will be generated for each client IP address.

Image from Gyazo

More information


If you have any other questions, please contact us or check out Our Slack Community.