Caching best practices

Initial request

When a client issues a request and receives a 200 OK response containing a response body, the client MUST cache:

The response body, and
Any cache validation headers present in the response, specifically ETag and/or Last-Modified.

If the response contains a Cache-Control: max-age=<value> directive, the client MUST treat the response as fresh for the duration of max-age. During this period, the client MAY reuse the cached response to satisfy subsequent requests without contacting the server.

If no Cache-Control: max-age directive is present, the client MUST NOT treat the response as indefinitely fresh. The client SHOULD issue a new request on the next access.

Cache expiration

When the max-age value has expired, the cached response is considered stale. At this point the client MUST either:

Issue a conditional request to revalidate the cached resource (preferred), or
Issue a new unconditional GET request to retrieve the latest representation from the server.

Conditional requests

When revalidating a stale cached resource, the client MUST include a validation header if one is available in the cache. The header to use is determined as follows:

If both ETag and Last-Modified are cached, the client MUST use If-None-Match (ETags are more reliable.)
If only ETag is cached, the client MUST use If-None-Match.
If only Last-Modified is cached, the client MUST use If-Modified-Since.
If neither header is cached, the client MUST issue a new unconditional GET request.

Example (using If-None-Match)

BASH

GET /metadata/delivery/GLOBAL/btv/programmes HTTP/1.1

If-None-Match: "abc123"

Example (using If-Modified-Since)

BASH

GET /metadata/delivery/GLOBAL/btv/programmes HTTP/1.1

If-Modified-Since: Wed, 17 Sep 2025 10:00:00 GMT

Server responses to conditional requests

304 Not Modified

If the resource has not changed, the server MUST return a 304 Not Modified response with no response body. Upon receiving this, the client MUST continue using the cached representation.

200 OK

If the resource has changed, the server MUST return a 200 OK response containing the updated resource representation and updated cache validation headers. The client MUST replace the previously cached representation with the new response.

Server error handling

If the server returns a 5xx response during revalidation or an unconditional request, the client MAY continue serving the most recently cached representation until the next retry attempt. Retry timing SHOULD follow the project's standard retry policy.

Request flow example

1. Initial request

BASH

GET /metadata/delivery/GLOBAL/btv/programmes HTTP/1.1

2. Server response

HTTP/1.1 200 OK

ETag: "abc123"

Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

Cache-Control: max-age=3600

The client caches the response body, ETag, and Last-Modified, and treats the response as fresh for 3600 seconds.

3. Cache expires – conditional request

BASH

GET /metadata/delivery/GLOBAL/btv/programmes HTTP/1.1

If-None-Match: "abc123"

4. Resource unchanged

HTTP/1.1 304 Not Modified

5. Client behaviour

The client continues using the cached representation.