Cache

The responses of endpoints that read data can be cached, so a repeated call with the same data is answered without running the API again. Per endpoint settings, the cache page and the X-Cache header are available from v10.0.0

Enable the cache

The cache is enabled for all endpoints in the cache settings:

Name	Description
Cache Enabled	Cache the responses of the endpoints that have the cache on. Default: no
Cache Time	How long a response is cached, in seconds. Default: 86400 (1 day). An endpoint can have its own cache time
Clear the cache when an entry changes	Clear the whole cache when an entry is saved or deleted, in the CP, via the API or by another add-on. Default: yes

A response is cached per member and per request data, only successful responses are cached. The cache key contains the site, so every site of an MSM install has its own cache.

Per endpoint

On the edit page of an endpoint the cache of that endpoint is set:

Name	Description
Cache	Default follows the API (e.g. read_entry is cached by default), On or Off
Cache Time	The cache time of this endpoint in seconds. Leave empty to use the cache time of the settings

Endpoints that change data (POST, PUT, PATCH, DELETE) are never cached. When they are called, they clear the cache of all sites. Saving an endpoint in the CP clears the cache of that endpoint.

Cache page

The Cache page in the CP shows the endpoints that can be cached, grouped per API, with:

• whether the cache is on or off, and whether that is the default of the API;
• the cache time, and whether it is the cache time of the settings;
• the cache hit rate: the part of the cached calls that was answered from the cache, from the API logs.

Filter on the cache (on/off), the API and a keyword. Select endpoints and choose Clear cache to clear their cache of the current site. Clear all cache clears the cache of all endpoints of all sites. Before v10.0.0 this page only had a Clear cache button.

X-Cache header

The response of an endpoint with the cache on has an X-Cache header: MISS when the response was not in the cache yet, HIT when it came from the cache. The API logs show the same as the Cache column, the Endpoints overview shows the hit rate per endpoint.

curl -i 'https://your-domain.com/index.php/webservice/entry?data[entry_id]=1' \
  -H 'Authorization: Bearer <shortkey>'

HTTP/1.1 200 OK
X-Cache: HIT

For API developers

An API sets the default with cachable on a method in its settings.json, and clear_cache on a method that changes data. The CP setting of an endpoint overrides cachable.

{
  "route": "/",
  "http_method": "GET",
  "method_name": "read_entry",
  "cachable": true
}