ResponseCache policy icon ResponseCache policy

About | Samples | Element reference | Flow variables | Error codes  

What

Uses a cache to store and retrieve data from a backend resource, reducing the number of requests to the resource.

Where

This policy can be attached in the following locations. See the samples for specific attachment guidance in different situations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request              
              Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

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 Edge 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>
        <TimeoutInSec>600</TimeoutInSec>
    </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

HTTP headers and query parameters are automatically populated as variables when a request is received. Any HTTP header is available as request.header.{header_name}, for example request.header.user-agent. Any query parameter is available as request.queryparam.{queryparam_name}, for example request.queryparam.action.

The following example shows how to have the cache lookup skipped and have the cache refreshed.

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>
        <TimeoutInSec>600</TimeoutInSec>
    </ExpirySettings>
</ResponseCache>

For more information about conditions, see Create dynamic API flows using 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>
    <FaultRules/>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" type="string"/>
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSec ref="">300</TimeoutInSec>
    </ExpirySettings>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
</ResponseCache>

<ResponseCache> attributes

<AssignMessage async="false" continueOnError="false" enabled="true" name="a_name">
Field Name Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The internal name of the policy. This name is referenced in Step elements to attach the policy to a Flow.

Note: Characters you can use in the name are restricted to: A-Z0-9._\-$ %. The Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

N/A Required

<CacheKey> element

Configures a unique pointer to a piece of data stored in the cache.

<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.

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.

<CacheResource> element

Specifies the cache where messages should be stored. A default cache is available.

<CacheResource>cache_to_use</CacheResource>

Default:

N/A

Presence:

Optional

Type:

String

For more about configuring caches, see Manage caches for an environment.

<ExpirySettings>/<ExpiryDate> element

Specifies the date on which a cache entry should expire. Use the form mm-dd-yyyy.

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

Default:

N/A

Presence:

Optional

Type:

String

Attributes

<TimeoutInSeconds 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> element

Specifies when a cache entry should expire.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

Default:

N/A

Presence:

Required

Type:

N/A

<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 supercedes 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 <CacheKey> entry with the <KeyFragment> apiAccessToken and a <Global> scope, each entry is stored as orgName__envName__apiAccessToken, followed by the serialized value of the access token. For an API proxy deployed in an environment called 'test' in an organization called 'apifactory', access tokens would be stored under the following cache key: apifactory__test__apiAccessToken.

APIProxy

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:

  • If the policy is attached to the ProxyEndpoint flow, prefix is of the form ApiProxyName_ProxyEndpointName.
  • If the policy is attached at TargetEndpoint, prefix is of the form ApiProxyName_TargetName.

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.

<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.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Default:

N/A

Presence:

Optional

Type:

String

<ExpirySettings>/<TimeoutInSeconds> element

The number of seconds after which a cache entry should expire.

<ExpirySettings>
    <TimeoutInSec ref="duration_variable">seconds_until_expiration</TimeoutInSec>
</ExpirySettings>

Default:

N/A

Presence:

Optional

Type:

Integer

Attributes

Attribute Description Default Presence Type
ref Variable with the timeout 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 .

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Default:

 

Presence:

Optional

Type:

String

Attributes

Attribute Description Default Presence Type
ref Variable with the expiration time value. N/A Optional String
 

Usage notes

ResponseCache can be configured to save and periodically refresh copies of response messages. As apps make requests to the same URI, Apigee Edge can be configured to return cached responses, rather than forwarding those requests to the backend server.

ResponseCache is commonly used when backend data is updated only periodically. For example, an API that exposes weather report data might only refresh the weather data once every ten minutes. By returning cached responses and refreshing once every ten minutes, ResponseCache decreases the number of request reaching the backend, and also eliminates a network hop for a significant portion of requests to the API.

There are two main benefits to ResponseCache:

  • Reduced latency: The request is satisfied from the cache (removing a network hop), so the response is returned in a shorter time, making the API more responsive.
  • Reduced network traffic: Representations are reused, so the impact of processing duplicate or redundant requests is reduced. ResponseCache reduces the amount of bandwidth consumed overall.

Unlike other policies, a ResponseCache policy must be attached to both request and response paths within a Flow.

You can configure the ResponseCache proxy to also look at certain HTTP response caching headers and take appropriate actions according to the directives of those headers. For example, on responses from backend targets, Edge supports the Cache-Control header, which can be used to control the maximum age of a cached response, among other directives. For more information, see HTTP response caching.

The name attribute for this policy is restricted to these characters: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Cached response messages are returned to requesting apps based on request message keys configured in the policy. At runtime, Apigee Edge inspects request messages for a 'key' that you specify. A key is a piece of information (such as query parameter) common to all request messages whose responses you need to cache. When a key match occurs, Edge returns the cached response, instead of forwarding the request to the backend service.

Attaching a ResponseCache policy

The ResponseCache policy type is unique in that it must be attached to both the request and response Flow in an API proxy.

ResponseCache policies are usually attached to the ProxyEndpoint PreFlow Request and Response, as in this example:

<PreFlow name="PreFlow">
    <Request>
        <Step><Name>ResponseCache</Name></Step>
    </Request>
    <Response>
        <Step><Name>ResponseCache</Name></Step>
    </Response>
</PreFlow>

Note: ResponseCache relies on a default cache resource configured for your organization when your Apigee Edge account is provisioned. For instructions on configuring cache resources, see Optimize performance using cache. If you have questions about your cache resource configuration, contact Apigee Support.

For a working ResponseCache policy, see the API Platform samples Using the samples on GitHub.

Flow variables

The following predefined Flow variables are populated when a ResponseCache policy is executed. For more information about Flow variables, see 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

Error Code Message
CacheNotFound Cache {0}, not found in organization : {1}
InvalidCacheResourceReference Invalid cache resource reference {0} in Step definition {1}. Context {2}
EntryCannotBeCached Entry {0} can not be cached. Only serializable entries are cached.
CannotDeleteStepDefinition Step definition {0} should be detached before deletion
ResponseCacheStepAttachmentNotAllowedReq Response cache step definition {0} can not be attached more than once in the request path
ResponseCacheStepAttachmentNotAllowedResp Response cache step definition {0} can not be attached more than once in the response path
InvalidTimeout CacheLookupTimeoutInSeconds{0} value should be greater than zero

Schema

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

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)