Was this helpful?

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.

When ResponseCache is employed in a proxy, Edge also looks at certain HTTP response caching headers and takes 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.

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 working ResponseCache policy, see the [API Platform samples Using the samples on GitHub.

Sample

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

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

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">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSec>6000</TimeoutInSec>
    </ExpirySettings>
</ResponseCache>

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

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

the response is cached.

The second request within 10 minutes to:

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

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">
    <Request>
        <Step><Name>ResponseCache</Name></Step>
    </Request>
    <Response>
        <Step><Name>ResponseCache</Name></Step>
    </Response>
</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}-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>
        <TimeoutInSec>600</TimeoutInSec>
    </ExpirySettings>
</ResponseCache>

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.
KeyFragment
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
CacheLookupTimeoutInSeconds
(Optional)
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" />
TimeOfDay A specific time (hh:mm:ss) of day when the cache expires.
ExpiryDate Specifies the date (mm-dd-yyyy) when the cache expires.
Expiry settings are overridden by the max-age and s-maxage directives of the Cache-Control header. See also HTTP response caching.

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.

Comments

It would be great: when there is a cache Hit, to set variables for accessing the expiration time of the cache entry, so the response can have proper HTTP cache-control headers, and the developer knows how long to cache the response in the client.

Hi Carlos - Can you please post this enhancement request to http://stackoverflow.com/questions/tagged/apigee, and add the Apigee tag to it? Thanks. Floyd

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.