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.
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.
x-cache
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.
age
Number of seconds since the response was cached.
x-cache-hits
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.
In the configuration dialog, enter the cache duration (in seconds) next to "Cache".
Click [Update] when you are done.
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.
Note that this button is only displayed if you have set a cache duration for the endpoint.
By API
To clear the cache of all the endpoints of an API, click [Clear cache] at the top of the endpoint list screen.
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:
HostAccept-EncodingAcceptOrigin
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.
Cookie authentication
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.
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.
More information
Support
If you have any other questions, please contact us or check out Our Slack Community.