Cache-Control
The HTTP Cache-Control header is used for both HTTP requests and HTTP responses. It is responsible for holding directives related to controlling caches for clients and intermediaries.
Usage
The Cache-Control header is used to control caches in client browsers and intermediate services such as proxies and content delivery networks (CDNs). Several directives are used for HTTP requests, HTTP responses, or both.
| Directive | Request | Response |
|---|---|---|
| max-age | X | X |
| max-stale | X | |
| min-fresh | X | |
| s-maxage | X | |
| no-cache | X | X |
| no-store | X | X |
| no-transform | X | X |
| only-if-cached | X | |
| must-revalidate | X | |
| proxy-revalidate | X | |
| must-understand | X | |
| private | X | |
| public | X | |
| immutable | X | |
| stale-while-revalidate | X | |
| stale-if-error | X |
Note
Clients may not support all of the directives. When an client encounters a directive that it does not recognize or support, then the directive will be ignored.
Request directives
max-age
The max-age directive is used by a client to indicate that responses stored within the specified number of seconds will be accepted. Invalid values for max-age, such as a negative value or a string literal, are generally be treated as 0.
Cache-Control: max-age=<seconds>
Setting max-age=0 is sometimes used to indicate that the cache is not to be used. This is an artifact of HTTP/1.0, as many implementations did not support the no-cache directive.
max-stale
The max-stale directive is used by a client to indicate that they will accept stale HTTP responses up to a certain number of seconds. This differs from max-age, as max-stale begins once the max-age expires.
Cache-Control: max-stale=<seconds>
This directive might be used by a client when an origin server is offline, and HTTP responses that are a little bit old are generally still acceptable.
min-fresh
The min-fresh directive is used by a client to indicate that it will allow a stored HTTP response that will remain fresh for a specified number of seconds. Essentially, this requires that the HTTP response not only be fresh but also that it won’t be updated for a minimum amount of time.
Cache-Control: min-fresh=<seconds>
no-cache
A client sends the no-cache directive to require the cache to validate the HTTP response in advance of sending it. This is sometimes used to force the reloading of a resource.
Cache-Control: no-cache
Note
To prevent a cache from storing a response, the no-store directive is used.
no-store
A client sends the no-store directive to ask caches not to store the HTTP request or the corresponding HTTP response.
Cache-Control: no-store
no-transform
A client sends the no-transform directive if the HTTP response is not to be manipulated. For example, graphics files might normally be scaled by a content provider to save bandwidth but this directive prevents such actions. Regardless of whether an intermediary is responsible for Caching or simply forwarding, this directive holds.
Cache-Control: no-transform
only-if-cached
A client sends the only-if-cached directive to HTTP request that any stored HTTP response is expected to be returned.
Cache-Control: only-if-cached
Response directives
max-age
The max-age directive is sent by a server to indicate that the HTTP response will remain fresh for a specified number of seconds after it is generated. Essentially, it informs caches how long it will remain fresh. Importantly, the number of seconds indicates the period from which the content was generated, as opposed to received. This means that any time spent in transit or stored in the caches of intermediaries is deducted from the allowance.
Cache-Control: max-age=<seconds>
s-maxage
The s-maxage, shared max-age, directive is the same as max-age, except that it is intended for shared caches such as proxy servers. When both s-maxage and max-age are included, a shared cache will ignore the latter.
Cache-Control: s-maxage=<seconds>
no-cache
The no-cache directive is sent by the server to direct caches to first validate responses from the origin server before sending them.
Cache-Control: no-cache
Note
If the intention is to direct caches not to store the result then the no-store directive is recommended to be used instead.
no-store
A server includes the no-store directive to prevent the storing of the HTTP response in any cache.
Cache-Control: no-store
no-transform
A server sends the no-transform directive to ensure that intermediaries do not manipulate the HTTP response before it is forwarded to the client, regardless of whether it is cached.
Cache-Control: no-transform
must-understand
The server sends the must-understand directive to indicate that caches is expected to store the HTTP response only in cases where it recognizes the status code and understands the requirements.
Cache-Control: must-understand
For fallback purposes, the must-understand directive is recommended to be used in conjunction with no-store in the case the must-understand directive is unsupported by a cache and thus ignored.
Cache-Control: must-understand, no-store
private
The private directive is sent by a server to instruct that the HTTP response can only be stored in a private cache, such as the one maintained by an end user's browser.
Cache-Control: must-understand
public
The public directive is included in a server’s HTTP response to indicate that it can be stored in a shared cache. Caches are not permitted to store HTTP responses that contain the HTTP Authorization header unless they are accompanied by the public directive.
Cache-Control: public
Note
The public directive is unnecessary if must-revalidate or s-maxage are present in the HTTP response.
immutable
The immutable directive indicates a guarantee by the server that the HTTP response will not be updated while it is still fresh. This can be used to avoid unnecessary conditional HTTP requests.
Cache-Control: immutable
stale-while-revalidate
When a server sends the stale-while-revalidate directive, it extends the period that it can be reused for. Specifically, after a HTTP response is stale, it can be reused provided that the HTTP response is validated in the background.
Cache-Control: stale-while-revalidate=<seconds>
Once revalidated, the cache will once again appear fresh. This process is used to obscure the latency involved in revalidating the response.
must-revalidate
The server includes the must-revalidate directive to instruct caches that they can reuse the HTTP response as long as it is fresh. After the HTTP response expires, it must be validated before serving it. This is intended to prevent the reuse of stale HTTP responses when they are disconnected from the origin server.
Cache-Control: must-revalidate
If the cache is not able to validate the HTTP response then a 504 Gateway Timeout response will be returned.
proxy-revalidate
The proxy-revalidate directive is identical to must-revalidate, except that it is intended for shared caches such as proxy servers and CDNs.
Cache-Control: proxy-revalidate
stale-if-error
When the stale-if-error directive is included in a HTTP response, it means that a stale HTTP response can be used when the origin server is reporting one of the following HTTP error response status codes:
After the HTTP response is stale, as long as it is within the specified number of seconds that the server is responding with one of these 5XX error codes, the HTTP response can be reused.
Cache-Control: stale-if-error=<seconds>
Multiple Directives
Multiple directives can be sent with multiple Cache-Control HTTP headers or the same line in a comma-delimited format. In either case, if conflicting directives are specified then the most restrictive combination will be applied.
Takeaway
The Cache-Control header is used to hold various cache-related instructions that can apply to HTTP requests, HTTP responses, or both. A variety of use cases can be covered using appropriate combinations of directives.