Caching - Reference | Kayako Developers

Contents

We strongly advise you to implement caching in your API client.

Caching does not only allow to reduce network load, but it also:

Helps to ensure that the resource you work with has not been modified by others
Allows to fetch only new or updated resources
Reduces load of our API service this way protecting its quality

These makes caching implementation significant for API clients.

ETag response header

An API response can include the ETag HTTP header holding the hash of the resource or collection that comes with the response:

HTTP/1.1 200 OK
Content-Type: application/json
ETag: 1653fb55ce4603b2f3def1903eb81333
X-API-Version: 1

In our API service the value of the ETag HTTP header represents the state of the delivered resource itself, i.e. does not include nested resources. This means that for the collection it considers only IDs of contained resources.

If-Match request header

To ensure that you work with the same version of the resource include the If-Match HTTP header with the ETag value into your API request:

PUT /api/v1/base/user/1 HTTP/1.1
Host: brewfictus.kayako.com
If-Match: 1653fb55ce4603b2f3def1903eb81333

In this case the action will be performed only if the specified hash matches the resource's current hash, i.e. if the resource has not been modified.

Otherwise, the API service will return the RESOURCE_MODIFIED error with the 412 (Precondition Failed) HTTP status code.

Consider always using the If-Match or the If-Unmodified-Since HTTP header with PUT and DELETE requests.

If-None-Match request header

To retrieve a resource only if it has been modified include the If-None-Match HTTP header with the ETag value into your API request:

GET /api/v1/base/user/1 HTTP/1.1
Host: brewfictus.kayako.com
If-None-Match: 1653fb55ce4603b2f3def1903eb81333

If the resource was not modified the API service will return the 304 (Not Modified) HTTP status code (with no body).

Consider always using the If-None-Match or the If-Modified-Since HTTP header with GET requests to enable client-side caching.

Last-Modified response header

An API response can include the Last-Modified HTTP header holding the date when the resource or collection was modified last time:

HTTP/1.1 200 OK
Content-Type: application/json
Last-Modified: Fri, 14 Aug 2015 18:39:41 +0000
X-API-Version: 1

If-Modified-Since request header

To retrieve a resource only if it has been modified since the last time you saw it include the If-Modified-Since HTTP header with the appropriate value into your API request:

GET /api/v1/base/user/1 HTTP/1.1
Host: brewfictus.kayako.com
If-Modified-Since: Fri, 14 Aug 2015 18:39:41 +0000

If the resource was not modified the API service will return the 304 (Not Modified) HTTP status code (with no body).

Consider always using the If-Modified-Since or the If-None-Match HTTP header with GET requests to enable client-side caching.

If-Unmodified-Since request header

To ensure that the resource was not modified since the last time you saw it include the If-Unmodified-Since HTTP header with the appropriate value into your API request:

PUT /api/v1/base/user/1 HTTP/1.1
Host: brewfictus.kayako.com
If-Unmodified-Since: Fri, 14 Aug 2015 18:39:41 +0000

If the resource was modified the API service will return the RESOURCE_MODIFIED error with the 412 (Precondition Failed) HTTP status code.

Consider always using the If-Unmodified-Since or the If-Match HTTP header with PUT and DELETE requests.

AJAX Caching Mode

The default algorithm of generating values for the ETag and the Last-Modified headers slightly differs from what is expected by web browsers and proxies. Thus, pure HTTP declares the ETag value as a hash of the content while REST API uses it as a hash of the resource.

As the default caching mode can cause some unexpected behavior of the API when used in a web browser or through a HTTP proxy we introduced the special AJAX mode.

In the AJAX caching mode values of the ETag and the Last-Modified HTTP headers represent a version of the content that also includes related resources. Therefore, this mode should not be used for the concurrency control.

The AJAX caching mode gets enabled when the API request contains the X-Requested-With HTTP header with the special value XMHTTPRequest (such header and its value is commonly used by web browsers' JavaScript engines).