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.

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


For example, assume that you need responses to the following API to be cached for ten minutes.


The query parameter w, which designates a WOIED, can be used as a CacheKey. With w set as CacheKey, 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.

<ResponseCache name="ResponseCache">
        <KeyFragment ref="request.queryparam.w" />

The first time the API proxy receives a request message for:


the response is cached.

The second request within 10 minutes to:


results in a cache hit. The cached response is returned to the app, and no request is forwarded to backend service.

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.

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

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. For example, the following configuration refreshes the cached response for the configuration below:

'http://{org_name}' -H "bypass-cache:true"
<ResponseCache name="ResponseCache">
        <KeyFragment ref="request.queryparam.w" />
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

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 more information about conditions, see Create dynamic API flows using conditions.

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.

Configuring the ResponseCache policy

Configure the ResponseCache policy using the following elements.

Field Name Description
CacheResource (Optional) Specifies the cache where messages should be stored. A default cache is available for all organizations on Apigee Edge.
Scope (Optional)
Used to construct the prefix, when Prefix in CacheKey is not provided. If Prefix is provided, then Scope is ignored.
Permitted values are Exclusive, Global, Application, Proxy, and Target.
  • Exclusive (default): ApiProxyName_ProxyEndpointName if the policy is attached to the ProxyEndpoint Flow. ApiProxyName_TargetName if the policy is attached at TargetEndpoint Flow.
  • Global: CacheKeys are shared across all API proxies deployed in the environment.
  • Application: ApiProxyName (the name of the API proxy) is used as the prefix for all cache keys.
  • Proxy: ApiProxyName_ProxyEndpointName (the name of the ProxyEndpoint configuration) is used as the prefix for all cache keys.
  • Target: ApiProxyName_TargetEndpointName (the name of the TargetEndpoint configuration) is used as the prefix for all cache keys.
CacheKey (Optional) Prefix
Used for matching requests to the cached response.
When specified, the CacheKey Prefix is used as the prefix for all entries stored in the Cache by the policy.
A CacheKey Fragment can either contain a key or a value.
All specified fragments combined (plus the prefix) are concatenated to create the CacheKey. For example, if a request message has headers id1=1 & id2=1, the cache key is Apigee__1__2.
SkipCacheLookup (Optional) Valid values: true/false
SkipCachePopulation (Optional) Valid values: true/false
Sets a timeout for cache lookups, in seconds.
ExpirySettings (Optional) TimeoutInSeconds

Duration (in seconds, ss) to leave for the cached entry. This value can also be set as a variavle, for example, as an HTTP header: <TimeoutInSec ref="response.header.timeout" />

Note: Expiry settings are overridden by the max-age and s-maxage directives of the Cache-Control header when UserResponseCacheHeaders is set to true

TimeOfDay A specific time (hh:mm:ss) of day when the cache expires.
ExpiryDate Specifies the date (mm-dd-yyyy) when the cache expires.

If set to true, the Accept-* headers of the request are used to build the cache key. (Default: false

See "How are cache keys generated?" in HTTP response caching.

If set to true, expiry (TTL) directives specified in the Cache-Control header (max-age and s-maxage) take precedence over and override the behavior of the Expires header. In other words, if this flag is set to true, Edge ignores the Expires response header. (Default: false)

Configuring Edge to use HTTP cache headers

The following policy configuration uses UseAcceptHeader and UseResponseCacheHeaders elements to instruct Edge to use Accept-* headers to calculate cache keys and to consider HTTP response cache headers like Cache-Control. For more information on how Edge uses HTTP cache headers, see HTTP response caching.

<ResponseCache name="response_cache">
        <KeyFragment ref="request.header.key1"/>

ResponseCache 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

Policy-specific 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

Policy 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?)