Caching REST API Response

1. Caching

Caching is the ability to store copies of frequently accessed data in several places along the request-response path.

When a consumer requests a resource representation, the request goes through a cache or a series of caches (local cache, proxy cache, or reverse proxy) toward the service hosting the resource.

If any of the caches along the request path has a fresh copy of the requested representation, it uses that copy to satisfy the request. If none of the caches can satisfy the request, the request travels to the service (or origin server as it is formally known).

By using HTTP headers, an origin server indicates whether a response can be cached and, if so, by whom, and for how long.

Caches along the response path can take a copy of a response, but only if the caching metadata allows them to do so.

Optimizing the network using caching improves the overall quality-of-service in the following ways:

• Reduce bandwidth
• Reduce latency
• Reduce load on servers
• Hide network failures

2. Caching in REST APIs

Being cacheable is one of the architectural constraints of REST.

• GET requests should be cachable by default – until a special condition arises. Usually, browsers treat all GET requests as cacheable.
• POST requests are not cacheable by default but can be made cacheable if either an Expires header or a Cache-Control header with a directive, to explicitly allows caching, is added to the response.
• Responses to PUT and DELETE requests are not cacheable at all.

Please note that HTTP dates are always expressed in GMT, never in local time.

3. Cache Control Headers

Below given are main HTTP response headers that we can use to control caching behavior:

3.1. Expires

The Expires HTTP header specifies an absolute expiry time for a cached representation. Beyond that time, a cached representation is considered stale and must be re-validated with the origin server.

To indicate that a representation never expires, a service can include a time up to one year in the future.

Expires: Fri, 20 May 2016 19:20:49 GMT

3.2. Cache-Control

The header value comprises one or more comma-separated directives. These directives determine whether a response is cacheable, and if so, by whom, and for how long e.g. max-age or s-maxage directives.

Cache-Control: max-age=3600

Cacheable responses (whether to a GET or to a POST request) should also include a validator — either an ETag or a Last-Modified header.

3.3. ETag

An ETag value is an opaque string token that a server associates with a resource to uniquely identify the state of the resource over its lifetime.

If the resource at a given URL changes, a new Etag value must be generated. A comparison of them can determine whether two representations of a resource are the same.

While requesting a resource, client sends the ETag in If-None-Match header field to the server. The server matches the Etag of the requested resource and the value sent in If-None-Match header. If both values match the server sends back a 304 Not Modified status, without a body, which tells the client that the cached version of the response is still good to use (fresh).

ETag: "abcd1234567n34jv"

3.4. Last-Modified

Whereas a response’s Date header indicates when the response was generated, the Last-Modified header indicates when the associated resource was last changed.

This header is used as a validator to determine if the resource is the same as the previously stored one by the client’s cache. Less accurate than an ETag header, it is a fallback mechanism.

The Last-Modified value cannot be greater than Date value. Note that Date header is listed in the forbidden header names.

Last-Modified: Fri, 10 May 2016 09:17:49 GMT