Caching

Conditional HTTP caching

It is not recommended for a client to blindly cache content. Instead, the client can ask the server whether or not a resource has been updated. HTTP provides a way to do this with conditional caching. A client can make a request to the server and check whether the server has a new version of the resource available. If the resource has not changed, the server will respond with http code 304 - Not Modified and no body. Otherwise, the server will respond with http code 200 - Success and the updated resource in the response body.

The Netilion API supports conditional caching on all endpoints that return a single resource such as

/v1/assets/{id}

and also for specification endpoints like

/v1/assets/{id}/specifications

Conditional HTTP Caching does not reduce the number of http requests from a client, but by skipping of the rendering process of unmodified resources the server can respond faster, the responses are much lighter (no body) and the server load is reduced.

There are two headers that support this:

ETag

When a server returns a response, it includes an ETag (entity tag) as an HTTP response header. Subsequent HTTP requests asking whether the resource has changed since the last request can send the stored ETag via the If-None-Match header.

Last-Modified timestamp

The second header is the Last-Modified header. This returns a timestamp of the last modification to the resource. The client can then include an If-Modified-Since header with the Last-Modified timestamp value to ask the server if the resource has been modified since the last request.

Included resources

When checking whether the resource has changed since the version identified by the ETag or timestamp, only the resource itself is considered, not any resource that may be included in the response via the include parameter.

For example, if the client requests the asset with ID 42 including the product via

/v1/assets/42?include=product

and uses the returned ETag in another request to the same URL, the server will return http code 304 - Not Modified, even if the name of the product has changed in the meantime, because the requested resource (asset with ID 42) has not changed.

If the client wants to be sure that all the fields in the included resources are up to date, no conditional cache header should be sent within the request.

General response caching

The stale method is only implemented for the show methods. For all other GET requests, the default handling of caching works as defined below. When the client sends an ETag, the server creates the response body and generates an ETag for that body. The ETag calculated by the server and the ETag from the client request are compared. If they match, the server returns http code 304 - Not Modified.

This type of caching is not as fast as the stale checking because the response body must be created on the server, to build the correct ETag, even if it’s not part of the response sent to the client.