Working with cache keys

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

When using cache policies, you ensure the uniqueness of cached value keys by configuring cache keys. A cache key, along with other values you can configure, gives you a reliable way to get out the same data that you put in. You use cache keys with the Populate Cache policy, LookupCache policy, InvalidateCache policy, and Response Cache policy.

The values of configuration elements -- <CacheKey>/<KeyFragment>, <Scope>, and <Prefix> -- are concatenated to create an identifier that is associated with the value you put into the cache. You use this same configuration to retrieve the value.

With the following cache policy configuration elements, you can create a cache key:

These values are concatenated in the following form, with <Scope> or <Prefix> values separated from KeyFragment values by double-underscores. Multiple KeyFragment values are also separated by double underscores.

scope | prefix__keyfragment[__keyfragment]

With the Response Cache policy, you can optionally append this cache key with values from the response Accept header.

Using <CacheKey>

The <CacheKey> element configures how Edge will create a unique identifier (a key) for each cache entry it creates. When Edge retrieves the cached value, it uses the cache key to locate the correct value. In the ResponseCache policy, one configuration defines the key for both caching and retrieval. In the PopulateCache and LookupCache policies, each policy must have identical <CacheKey>elements to ensure that a value retrieved from the cache corresponds to a value put there.

The <CacheKey> element can include multiple <KeyFragment> elements. At runtime, the values specified by <KeyFragment> elements are concatenated with two underscores between them in to make up part of the cache key.

For example, the following configuration creates a value of hello__world for use in the cache key:

<CacheKey>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

You can also use a variable values in a cache key by referencing the variable in a <KeyFragment> element, as shown here:

<KeyFragment ref="variable_name"/>

For example, to make the cache key value incorporate the Content-Type of the request message, you do as follows:

<KeyFragment ref="request.header.Content-Type"/>

In the following configuration, the request.header.Content-Type variable has the value application/json.

<CacheKey>
  <KeyFragment>apiAccessToken</KeyFragment>
  <KeyFragment ref="request.header.Content-Type" />
  <KeyFragment>bar</KeyFragment>
</CacheKey>

This result a cache key ending with apiAccessToken__application/json__bar.

For a list of the variables you can use, see Variables reference.

Cache keys derived from query parameters

Using variables such as request.queryparam.<queryparam_name> and request.querystring, you can configure a cache key so that the key includes parts of a request's query string. For example, the following URL uses two query parameters -- param1 and param2 -- that you can use in your cache key:

http://myaccount.apigee.net/mydata?param1=value1&param2=value2

Your <CacheKey> element can incorporate these values with a configuration such as the following:

<CacheKey>
    <KeyFragment ref="request.queryparam.param1" />
    <KeyFragment ref="request.queryparam.param2" />
<CacheKey>

At runtime, the cache key would include the param values concatenated, as in the following:

other_key_parts__value1__value2

Keep in mind that when you use variables to insert values from parameters, the values will be concatenated in the order suggested by the <KeyFragment> element order. Also, note that Edge will use only those values that you specifically reference with <KeyFragment> elements. If your request query parameter lists vary, the variations won't be accounted for in the cache key.

An alternative is to use the request.querystring variable, which inserts the entire string of parameters literally as part of the cache key. Keep in mind that while this method accounts for all of the parameters, if the order of parameters varies from one request to the next then the key will be different. In other words, param1=value1&param2=value2 and param2=value2&param1=value1 don't result in the same cache key value.

For a list of the variables you can use, see Variables reference.

Using <Scope> and <Prefix>

The <Scope> and <Prefix> elements provide a way to augment the key with a namespace prefix. The values they represent are prepended to your cache key.

The <Scope> element is used by default. It is an enumeration whose values range from broad to narrow, with the narrowest as the default. This default value is used unless you specify another value or specify a <Prefix> element value. You can override the <Scope> value by using a <Prefix> element, and so specify a custom value for namespacing.

For example, the <Scope> value "Global" -- the broadest scope -- represents the organization and environment name. So if your proxy is deployed in an organization called 'mycompany' and an environment named 'prod', the resulting preprended value will be the following:

If you're using the Global scope with the cache key defined above, the result is as follows:

<Scope>Global</Scope>
<CacheKey>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>

As described in LookupCache policy, the scope can be configured for increasing specificity from Global to Exclusive. An Exclusive scope is the most specific, and therefore represents minimal risk of namespace collisions within a given cache. Each cache entry with an Exclusive scope is prefixed in the following form:

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__[serializedCacheKey]

For example, a cache key created from using the Exclusive value for <Scope> would look like the following:

apifactory__test__weatherapi__16__default__apiAccessToken