This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
This topic describes how Apigee handles HTTP/1.1 caching headers when you're using the ResponseCache policy. Apigee currently supports a subset of the HTTP/1.1 caching headers and directives (unsupported features are listed in this topic) received from backend target (origin) servers.
In addition, with certain headers Apigee takes action based on their directives. In some cases,
these HTTP/1.1 cache headers override whatever behavior is specified in the ResponseCache policy.
For example, if the Cache-Control
header is returned from a backend server, you can
have the header's s-maxage
directive potentially override other expiration settings
in the policy.
Header | Support |
---|---|
Cache-Control | Supported on responses returned from backend origin servers, but not client requests. Apigee supports a subset of directives. |
Expires | Supported. Can be overridden. |
Entity Tags (ETags) | Specific behavior for If-Match and If-None-Match. |
If-Modified-Since | On GET requests, header is passed to the origin server even if a valid cache entry exists. |
Accept-Encoding | Apigee sends either compressed or uncompressed responses depending on the incoming headers. |
Cache-Control
Apigee supports the Cache-Control
header only on responses returned from
backend origin servers (the HTTP/1.1 spec allows Cache-Control
headers in both
client requests and origin server responses). Origin servers can include both target endpoints
defined in an Apigee API proxy and those created using TargetServer API calls.
Cache-Control support limitations
Apigee supports a subset of Cache-Control
response header capabilities
defined in the HTTP/1.1 specification. Please note the following:
- Apigee does not support
Cache-Control
headers that arrive with inbound client requests. - Apigee supports only the notion of public caches. (According to the HTTP
specification,
Cache-Control
can either be public (shared) or private (single user).) - Apigee supports only a subset of
Cache-Control
response directives in the HTTP/1.1 specification. See Support for Cache-Control response header directives for details.
Support for Cache-Control response header directives
Apigee supports a subset directives from the HTTP/1.1 specification on responses from origin servers. The following table describes Apigee support for HTTP Cache-Control response header directives.
For more detailed information on the directives listed here, see Cache-Control in the HTTP/1.1 specification.
Cache-Control directive | How Apigee processes the directive |
cache-extension |
Not supported. |
max-age |
If your ResponseCache policy sets the This directive is overridden by the |
must-revalidate |
Not supported. All cache entries are deleted by Apigee as soon as they expire. |
no-cache |
Apigee caches the origin response, but it must be revalidated with the origin server before being used to satisfy any subsequent client requests. This rule allows the origin to return a 304 Not Modified response in order to indicate that the response should be returned from cache, thus saving the processing required to return the entire response. If the origin server returns a full response, it replaces the existing cache entry. Any field names specified with this directive are ignored. |
no-store |
Not supported. |
no-transform |
Not supported. |
private |
Not supported. If this directive is received, the origin response is not cached. Any field names are ignored. |
proxy-revalidate |
Not supported. All cache entries are deleted by Apigee as soon as they expire. |
public |
Apigee caches the origin response, even when other directives indicate otherwise. Per the HTTP/1.1 specification, the only exception to this rule is if the response includes an Authorization header. |
s-maxage |
If your ResponseCache policy sets the This directive is overrides the |
Expires
When the UseResponseCacheHeaders
flag in the ResponseCache policy is set to
true
, Apigee can use the Expires
header to determine the time to live
(TTL) of a cached entry. This header specifies a date/time after which a response's cache entry
is considered stale. This header allows servers to signal when it's okay to return a cached value
based on a time stamp.
Acceptable date formats for the Expires
header are described in the HTTP/1.1
specification. For example:
Expires: Thu, 01 Dec 1994 16:00:00 GMT
For detailed information on HTTP date/time formats, see Date/Time Formats in the HTTP/1.1 specification.
For more information on Expires
header, see
Header Field Definitions
in the HTTP/1.1 specification.
ETag
An entity tag (ETag) is an identifier associated with a requested resource. Using an ETag, a server can determine if the requested resource and the associated cached resource match. For example, the server could re-cache the response if it doesn't match what's currently cached. It could return the cached resource if the ETags match.
When a target endpoint sends a response back to Apigee with an ETag, Apigee caches the ETag along with the response.
You can read more about Entity Tags in Protocol Parameters in the HTTP/1.1 specification.
If-Match
With the If-Match
request header, a cached entity is current if the ETag in the
header matches the cached ETag. Any requests other than GET that specify an If-Match
header are passed on to the origin server to ensure that any origin caching facilities have a
chance to process the request.
You can read more about If-Match
in
Header Field Definitions
in the HTTP/1.1 specification.
If Apigee receives an inbound GET request from a client that includes an If-Match
header:
If | Then |
---|---|
The If-Match header specifies one or more ETags |
|
The If-Match header specifies "*" |
The request is passed on to the origin server to ensure that any origin caching facilities have a chance to process the request |
A cache entry with the same request URI is found, but it contains only weak ETags | The entry must be revalidated by the origin server before being returned to the client |
The ETags comes from the origin server. | The ETag is returned unchanged to the client |
If-None-Match
With the If-None-Match
header, a cached entity is current if the ETag in the
header does not match the cached ETag. Requests other than a GET that contain this
header are passed to the origin server.
If Apigee receives an inbound GET request with this header:
If | Then |
---|---|
The If-None-Match header specifies one or more ETags |
|
The |
Apigee returns a 304 Not Modified status |
A cache entry with the same request URI is found but contains only weak ETags | The entry must be revalidated by the origin server before Apigee returns it to the client |
Apigee receives an ETag from an origin server | The ETag is returned unchanged to the client |
If-Modified-Since
If Apigee receives an If-Modified-Since
header in a GET request, it is
passed along to the origin server even if a valid cache entry exists.
This ensures that any updates to a resource that did not pass through Apigee are
accounted for. If the origin server returns a new entity, then Apigee replaces the existing cache
entry with the new value. If the server returns a 304 Not Modified status, Apigee returns the
response value if the cached response's Last-Modified
header indicates that it has
not changed.
Accept-Encoding
When an incoming request includes the header Accept-Encoding
with values of
gzip
, deflate
or compress
, the origin server responds with
compressed data. When subsequent requests come without the Accept-Encoding
headers,
they expect an uncompressed response. Apigee's response caching mechanism is capable of sending
both compressed and uncompressed responses depending on the incoming headers without going back
to the origin server.
You can have Accept header values appended to cache keys to make the keys more meaningful for each cached item. For more details, see "Configuring a cache key" in Response Cache policy.