This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The ResponseCache policy 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 anExtensible 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, seePolicy 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 thePopulateCache policy. That policy is used in conjunction with theLookupCache policy (for reading cache entries) and theInvalidateCache policy (for invalidating entries).

Samples

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">    <CacheKey>        <KeyFragment ref="request.queryparam.w" />    </CacheKey>    <ExpirySettings>        <TimeoutInSeconds>600</TimeoutInSeconds>    </ExpirySettings></ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache: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>

Element reference

The element reference describes the elements and attributes of the policy.

<?xmlversion="1.0"encoding="UTF-8"standalone="yes"?><ResponseCacheasync="false"continueOnError="false"enabled="true"name="Response-Cache-1"><DisplayName>ResponseCache1</DisplayName><Properties/><CacheKey><Prefix/><KeyFragmentref="request.uri"/></CacheKey><Scope>Exclusive</Scope><ExpirySettings><ExpiryDate/><TimeOfDay/><TimeoutInSecondsref="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:

<DisplayName> element

Use in addition to thename attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

<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><KeyFragmentref="variable_name"/><KeyFragment>literal_string</KeyFragment></CacheKey>

<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 ofUserToken__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, seeWorking 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>

<CacheResource> element

Specifies the cache where messages should be stored. Omit this element to use the included shared cache. You should specify aCacheResource by name if you wish to be able to administratively clear entries contained in the cache. For more on that, seeCaches API.

<CacheResource>cache_to_use</CacheResource>

<CacheKey>/<KeyFragment> element

Specifies a value that should be included in the cache key, creating a namespace for matching requests to cached responses.

<KeyFragmentref="variable_name"/><KeyFragment>literal_string</KeyFragment>

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, seeWorking with cache keys.

Attributes

<CacheKey>/<Prefix> element

Specifies a value to use as a cache key prefix.

<Prefix>prefix_string</Prefix>

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, seeWorking with cache keys.

<ExcludeErrorResponse> element

This policy can cache HTTP responses withany status code. That means both success and error responses can be cached, including 2xx and 3xx status codes.

Set this element totrue (default) to exclude the error responses. Set it tofalse 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, seeIntroduction to antipatterns.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

<ExpirySettings> element

Specifies when a cache entry should expire. When present,<TimeoutInSeconds> overrides both<TimeOfDay> and<ExpiryDate>.

<ExpirySettings><TimeOfDayref="time_variable">expiration_time</TimeOfDay><TimeoutInSecondsref="duration_variable">seconds_until_expiration</TimeoutInSeconds><ExpiryDateref="date_variable">expiration_date</ExpiryDate></ExpirySettings>

<ExpirySettings>/<ExpiryDate> element

Specifies the date on which a cache entry should expire. Use the formmm-dd-yyyy. When present, this element's sibling,<TimeoutInSeconds>, overrides<ExpiryDate>.

<ExpirySettings><ExpiryDateref="{date_variable}">expiration_date</ExpiryDate></ExpirySettings>

Attributes

<ExpiryDate ref="" />

<ExpirySettings>/<TimeOfDay> element

The time of day at which a cache entry should expire. Use the formhh: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><TimeOfDayref="time_variable">expiration_time</TimeOfDay></ExpirySettings>

Attributes

<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><TimeoutInSecondsref="duration_variable">seconds_until_expiration</TimeoutInSeconds></ExpirySettings>

<Scope>scope_enumeration</Scope>

You use the<Scope> element in conjunction with<CacheKey> and<Prefix>. For more information, seeWorking with cache keys.

Acceptable values

apifactory__test__weatherapi__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 alsoUsing the ResponseCache policy video on the use ofSkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

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 alsothis video on the use ofSkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

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 totrue to have a response cache entry's cache key appended with values from response Accept headers.

Apigee uses theAccept,Accept-Encoding,Accept-Language andAccept-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.

SeeConfiguring a cache key for more.

<UseAcceptHeader>false</UseAcceptHeader>

<UseResponseCacheHeaders> element

Set totrue 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

SeeSetting cache entry expiration for more details.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Usage notes

The maximum size for each cached object is 256 KB. (For detailed information on how Apigee processes cache, seeCache 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, seeSupport for HTTP response headers.

Setting cache entry expiration

As with thePopulateCache 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:

• NoCache-Control s-maxage value
• ACache-Control max-age value of 300
• AnExpires date in three days
• An<ExpirySettings>TimeoutInSeconds value of 600.

In this case, theCache-Controlmax-age value would be used for the TTL because it is lower than the<ExpirySettings> value and because there is noCache-Control s-maxage value (which takes precedence overmax-age).

Configuring a cache key

As with general purpose cache policies such as thePopulateCache 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, seeWorking 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, seeFlow variables reference.

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, seeWhat you need to know about policy errors andHandling 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.

Schema

Each policy type is defined by an XML schema (.xsd). For reference,policy schemas are available on GitHub.