This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
Caches data from a backend resource, reducing the number of requests to the resource. As apps make requests to the same URI, you can use this policy to return cached responses instead of forwarding those requests to the backend server. The ResponseCache policy can improve your API's performance through reduced latency and network traffic.
This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types.
You'll likely find ResponseCache most useful when backend data used by your API is updated only periodically. For example, imagine you have an API that exposes weather report data refreshed only every ten minutes. By using ResponseCache to return cached responses between refreshes, you can decrease the number of requests reaching the backend. This also reduces the number of network hops.
For general purpose short-term caching, considering using the PopulateCache policy. That policy is used in conjunction with the LookupCache policy (for reading cache entries) and the InvalidateCache policy (for invalidating entries).
Watch the following video for an introduction to the Response Cache policy.
Samples
10-minute cache
This sample shows how to have cached responses kept for 10 minutes.
Imagine that you have an API at the following URL:
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
You're using the query parameter w
as a cache key. Apigee checks the
value of the query parameter w
whenever a request is received. If a valid (that
is, non-expired) response is present in the cache, then the cached response message is
returned to the requesting client.
Now imagine that you have a ResponseCache policy configured as follows.
<ResponseCache name="ResponseCache"> <CacheKey> <KeyFragment ref="request.queryparam.w" /> </CacheKey> <ExpirySettings> <TimeoutInSeconds>600</TimeoutInSeconds> </ExpirySettings> </ResponseCache>
The first time the API proxy receives a request message for the following URL, the response is cached. On the second request within 10 minutes, a cache lookup occurs -- the cached response is returned to the app with no request forwarded to the backend service.
http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778
Skip cache lookup
The following example shows how to have the cache lookup skipped and have the cache refreshed. See also this video on the use of SkipCacheLookup.
The optional SkipCacheLookup condition (if configured) is evaluated in the request path. If the condition evaluates to true, then the cache look up is skipped and the cache is refreshed.
A common use of conditional cache refresh is a condition that defines a specific HTTP header that causes the condition to evaluate to true. A scripted client application could be configured to periodically submit a request with the appropriate HTTP header, explicitly causing the response cache to refresh.
For example, imagine a call to an API at the following URL:
'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"
Now imagine the following ResponseCache policy configured on that proxy. Note that the bypass-cache condition is set to true.
<ResponseCache name="ResponseCache"> <CacheKey> <KeyFragment ref="request.queryparam.w" /> </CacheKey> <!-- Explicitly refresh the cached response --> <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup> <ExpirySettings> <TimeoutInSeconds>600</TimeoutInSeconds> </ExpirySettings> </ResponseCache>
For more information about conditions, see Flow variables and conditions.
Element reference
The element reference describes the elements and attributes of the policy.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1"> <DisplayName>Response Cache 1</DisplayName> <Properties/> <CacheKey> <Prefix/> <KeyFragment ref="request.uri" /> </CacheKey> <Scope>Exclusive</Scope> <ExpirySettings> <ExpiryDate/> <TimeOfDay/> <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds> </ExpirySettings> <CacheResource>cache_to_use</CacheResource> <CacheLookupTimeoutInSeconds/> <ExcludeErrorResponse/> <SkipCacheLookup/> <SkipCachePopulation/> <UseAcceptHeader/> <UseResponseCacheHeaders/> </ResponseCache>
<ResponseCache> attributes
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
The following table describes attributes that are common to all policy parent elements:
Attribute | Description | Default | Presence |
---|---|---|---|
name |
The internal name of the policy. The value of the Optionally, use the |
N/A | Required |
continueOnError |
Set to Set to |
false | Optional |
enabled |
Set to Set to |
true | Optional |
async |
This attribute is deprecated. |
false | Deprecated |
<DisplayName> element
Use in addition to the name
attribute to label the policy in the
management UI proxy editor with a different, natural-language name.
<DisplayName>Policy Display Name</DisplayName>
Default |
N/A If you omit this element, the value of the policy's |
---|---|
Presence | Optional |
Type | String |
<CacheKey> element
Configures a unique pointer to a piece of data stored in the cache.
Cache keys are limited to a size of 2 KB.
<CacheKey> <Prefix>string</Prefix> <KeyFragment ref="variable_name" /> <KeyFragment>literal_string</KeyFragment> </CacheKey>
Default: |
N/A |
Presence: |
Required |
Type: |
N/A |
<CacheKey>
constructs the name of each piece of data stored in the cache.
The key is often set using a value from entity headers or query params. In those cases, you would
have the element's ref attribute specify a variable containing the key value.
At runtime, <KeyFragment>
values are prepended with either the
<Scope>
element value or <Prefix>
value. For example, the
following results in a cache key of
UserToken__apiAccessToken__
<value_of_client_id>:
<CacheKey> <Prefix>UserToken</Prefix> <KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.queryparam.client_id" /> </CacheKey>
You use the <CacheKey>
element in conjunction with
<Prefix>
and <Scope>
. For more information, see Working with cache keys.
<CacheLookupTimeoutInSeconds> element
Specifies the number of seconds after which an unsuccessful cache lookup will be considered a cache miss. If this occurs, flow resumes along the cache-miss path.
<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>
Default: |
30 |
Presence: |
Optional |
Type: |
Integer |
<CacheResource> element
Specifies the cache where messages should be stored. Omit this element to use the included
shared cache. You should specify a CacheResource
by name if you wish to be able to
administratively clear entries contained in the cache. For more on that, see Caches API.
<CacheResource>cache_to_use</CacheResource>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
<CacheKey>/<KeyFragment> element
Specifies a value that should be included in the cache key, creating a namespace for matching requests to cached responses.
<KeyFragment ref="variable_name"/> <KeyFragment>literal_string</KeyFragment>
Default: |
N/A |
Presence: |
Optional |
Type: |
N/A |
This can be a key (a static name that you provide) or a value (a dynamic entry set by referencing a variable). All specified fragments combined (plus the prefix) are concatenated to create the cache key.
<KeyFragment>apiAccessToken</KeyFragment> <KeyFragment ref="request.queryparam.client_id" />
You use the <KeyFragment>
element in conjunction with
<Prefix>
and <Scope>
. For more information, see Working with cache keys.
Attributes
Attribute | Type | Default | Required | Description |
---|---|---|---|---|
ref | string | No |
The variable from which to get the value. Should not be used if this element contains a literal value. |
<CacheKey>/<Prefix> element
Specifies a value to use as a cache key prefix.
<Prefix>prefix_string</Prefix>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
Use this value instead of <Scope>
when you want to specify your own value
rather than a <Scope>
-enumerated value. If defined,
<Prefix>
prepends the cache key value for entries written to the cache. A
<Prefix>
element value overrides a <Scope>
element
value.
You use the <Prefix>
element in conjunction with
<CacheKey>
and <Scope>
. For more information, see Working with cache keys.
<ExcludeErrorResponse> element
This policy can cache HTTP responses with any status code. That means both success and error responses can be cached, including 2xx and 3xx status codes.
Set this element to true
(default) to exclude the error responses. Set it to
false
if you do not want to exclude cache target
responses with HTTP error status codes.
For a discussion of Response Cache patterns in which this element is useful, see Introduction to antipatterns.
<ExcludeErrorResponse>true</ExcludeErrorResponse>
Default: |
true |
Presence: |
Optional |
Type: |
Boolean |
<ExpirySettings> element
Specifies when a cache entry should expire. When present, <TimeoutInSeconds>
overrides both <TimeOfDay>
and <ExpiryDate>
.
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> <ExpiryDate ref="date_variable">expiration_date</ExpiryDate> </ExpirySettings>
Default: |
N/A |
Presence: |
Required |
Type: |
N/A |
<ExpirySettings>/<ExpiryDate> element
Specifies the date on which a cache entry should expire. Use the form mm-dd-yyyy
.
When present, this element's sibling, <TimeoutInSeconds>
, overrides
<ExpiryDate>
.
<ExpirySettings> <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate> </ExpirySettings>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
Attributes
<ExpiryDate ref="" />
Attribute | Description | Default | Presence | Type |
---|---|---|---|---|
ref |
The variable from which to get the value. Should not be used if this element contains a literal value. |
N/A | Optional | String |
<ExpirySettings>/<TimeOfDay> element
The time of day at which a cache entry should expire. Use the form hh:mm:ss
.
When present, this element's sibling, <TimeoutInSeconds>
, overrides
<TimeOfDay>
.
Enter time of day in the format HH:mm:ss, where HH represents the hour on a 24-hour clock. For example, 14:30:00 for 2:30 in the afternoon.
For the time of day, the default locale and time zone will vary depending on where the code is running (which isn't knowable when you configure the policy).
<ExpirySettings> <TimeOfDay ref="time_variable">expiration_time</TimeOfDay> </ExpirySettings>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
Attributes
Attribute | Description | Default | Presence | Type |
---|---|---|---|---|
ref | Variable with the expiration time value. | N/A | Optional | String |
<ExpirySettings>/<TimeoutInSec> element
The number of seconds after which a cache entry should expire.
<ExpirySettings>/<TimeoutInSeconds> element
The number of seconds after which a cache entry should expire. When present, this element
overrides its siblings, <TimeOfDay>
and <ExpiryDate>
.
<ExpirySettings> <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds> </ExpirySettings>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
Attributes
Attribute | Description | Default | Presence | Type |
---|---|---|---|---|
ref | Variable with the timeout value. |
N/A
|
Optional | String |
<Scope> element
Enumeration used to construct a prefix for a cache key when a <Prefix>
element is not provided in the <CacheKey>
element.
<Scope>scope_enumeration</Scope>
Default: |
"Exclusive" |
Presence: |
Optional |
Type: |
String |
The <Scope>
setting determines a cache key that is prepended according to
the <Scope>
value. For example, a cache key would take the following form when
scope is set to Exclusive
:
orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [
serializedCacheKey ].
If a <Prefix>
element is present in <CacheKey>
, it
supersedes a <Scope>
element value. Valid values include the enumerations
below.
You use the <Scope>
element in conjunction with
<CacheKey>
and <Prefix>
. For more information, see Working with cache keys.
Acceptable values
Scope Value | Description |
---|---|
Global |
Cache key is shared across all API proxies deployed in the environment. Cache key is prepended in the form orgName __ envName __. If you define a |
Application |
API proxy name is used as the prefix. Cache key is prepended in the form orgName__envName__apiProxyName. |
Proxy |
ProxyEndpoint configuration is used as the prefix. Cache key is prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName . |
Target |
TargetEndpoint configuration is used as the prefix. Cache key prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName . |
Exclusive |
Default. This is the most specific, and therefore presents minimal risk of namespace collisions within a given cache. Prefix is one of two forms:
Cache key prepended in the form orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName For example, the full string might look like this: apifactory__test__weatherapi__16__default__apiAccessToken |
<SkipCacheLookup> element
Defines an expression that, if it evaluates to true at runtime, specifies that cache lookup
should be skipped and the cache should be refreshed. See also
Using the ResponseCache policy video on the use of SkipCacheLookup
.
<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
From the following example, if the bypass-cache variable is set to true in an incoming header, cache lookup is skipped and the cache is refreshed.
<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
<SkipCachePopulation> element
Defines an expression that, if it evaluates to true at runtime, specifies that a write to the
cache should be skipped. See also this
video on the use of SkipCachePopulation
.
<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>
Default: |
N/A |
Presence: |
Optional |
Type: |
String |
For example, the following would skip the cache write if the response status code was 400 or higher:
<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>
<UseAcceptHeader> element
Set to true
to have a response cache entry's cache key appended with values from
response Accept headers.
Apigee uses the Accept
, Accept-Encoding
, Accept-Language
and Accept-Charset
request headers when calculating the cache key. This approach
prevents a client from getting a media type they did not ask for.
For example, consider if two requests come in from the same URL, where the first request accepts gzip and the second does not. The first request will be cached, and the cached entry will (probably) be a gzipped response. The second request will read the cached value and may then return a gzipped entry to a client that is not capable of reading gzip.
See Configuring a cache key for more.
<UseAcceptHeader>false</UseAcceptHeader>
Default: |
false |
Presence: |
Optional |
Type: |
Boolean |
<UseResponseCacheHeaders> element
Set to true
to have HTTP response headers considered when setting the "time to
live" (TTL) of the response in the cache. When this is true, Apigee considers the values of the
following response headers, comparing the values with those set by
<ExpirySettings>
when setting time to live:
Cache-Control s-maxage
Cache-Control max-age
Expires
See Setting cache entry expiration for more details.
<UseResponseCacheHeaders>false</UseResponseCacheHeaders>
Default: |
false |
Presence: |
Optional |
Type: |
Boolean |
Usage notes
The maximum size for each cached object is 256 KB. (For detailed information on how Apigee processes cache, see Cache internals.)
Through configuration in the ResponseCache policy, you can have Apigee include HTTP response headers in setting cache entry expiration and cache keys. This section describes you can use the policy with headers to manage cache expiration and cache keys.
For more about how Apigee handles response headers with the ResponseCache policy, see Support for HTTP response headers.
Setting cache entry expiration
As with the PopulateCache policy, you can set a response cache entry's expiration (its time to live) using the
<ExpirySettings>
element. In the ResponseCache policy, you can also have Apigee
consider response headers when they're present.
To use response headers, you set the <UseResponseCacheHeaders>
element value to
true. That setting causes Apigee to consider the response headers, compare them with the value set
by <ExpirySettings>
, then use the lowest value between the two. When
considering the response headers, Apigee chooses the value available as described in the
following:
For example, imagine a response is cached with the following values:
- No
Cache-Control s-maxage
value - A
Cache-Control max-age
value of 300 - An
Expires
date in three days - An
<ExpirySettings>
TimeoutInSeconds
value of 600.
In this case, the Cache-Control
max-age
value would be used for the
TTL because it is lower than the <ExpirySettings>
value and because there is
no Cache-Control s-maxage
value (which takes precedence over
max-age
).
Configuring a cache key
As with general purpose cache policies such as the PopulateCache policy, with
ResponseCache you use <CacheKey>
and <Scope>
elements to
configure cache key creation for cache entries. With ResponseCache you can also make cache keys
more meaningful by having response Accept headers appended to key values.
For general information about configuring cache keys, see Working with cache keys. For
information about using Accept headers, see <UseAcceptHeader>
.
About cache encryption
Apigee and Apigee hybrid (version 1.4 and later): Cache and KVM data are always encrypted.
Flow variables
The following predefined Flow variables are populated when a ResponseCache policy is executed. For more information about Flow variables, see Flow variables reference.
Variables | Type | Permission | Description |
---|---|---|---|
responsecache.{policy_name}.cachename |
String | Read-Only | Returns the cache used in the policy |
responsecache.{policy_name}.cachekey |
String | Read-Only | Returns the key used |
responsecache.{policy_name}.cachehit |
Boolean | Read-Only | True if the policy execution is successful |
responsecache.{policy_name}.invalidentry |
Boolean | Read-Only | True if the cache entry in not valid |
Error codes
This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.
Error code prefix
N/A
Runtime errors
This policy does not throw any runtime errors.
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause | Fix |
---|---|---|
InvalidTimeout |
If the
<CacheLookupTimeoutInSeconds> element of the ResponseCache policy is set to a negative number,
then the deployment of the API proxy fails. |
build |
InvalidCacheResourceReference |
This error occurs if the <CacheResource> element in a ResponseCache policy is set to a
name that does not exist in the environment where the API proxy is being deployed. |
build |
ResponseCacheStepAttachmentNotAllowedReq |
This error occurs if the same ResponseCache policy is attached to multiple request
paths within any flows of an API proxy. |
build |
ResponseCacheStepAttachmentNotAllowedResp |
This error occurs if the same ResponseCache policy is attached to multiple response
paths within any flows of an API proxy. |
build |
InvalidMessagePatternForErrorCode |
This error occurs if either the <SkipCacheLookup> or the <SkipCachePopulation>
element in a ResponseCache policy contains an invalid condition. |
build |
CacheNotFound |
This error occurs if the specific cache mentioned in the error message has not been created on a specific Message Processor component. | build |
Fault variables
N/A
Example error response
N/A
Schema
Each policy type is defined by an XML schema (.xsd
). For reference, policy schemas
are available on GitHub.