When using a cache from a proxy, you can 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 data that you put in.

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

For reference about these elements, see LookupCache policy

With the following cache policy configuration elements, you can create a namespace in which values are unique:

Cache Configuration Element Description
CacheKey > KeyFragment Use CacheKey KeyFragment elements combine to specify a unique identifier for cache entries. KeyFragment values can be static literals or set from variables.
Scope or Prefix Use the Scope or Prefix elements to namespace cache keys. Scope enumerates a list of predefined values. The Prefix element overrides Scope with a value of your own choosing.

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]

Using CacheKey

The CacheKey element specifies a unique identifier for cache entries created from a PopulateCache policy. When you use a LookupCache policy to retrieve the cached values, you use a CacheKey element defined in the same way to get the same entry.

The CacheKey element can include multiple KeyFragment elements. Values from KeyFragment elements are concatenated with two underscores between them.

The following configuration creates a cache key of hello__world:

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

<KeyFragment ref="variable_name"/>

For example, to make the CacheKey value unique to the Content-Type of the request message, you do as follows:

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

This defines a KeyFragment as the value of the context variable request.header.Content-Type. In the configuration below, 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 of <Scope>__apiAccessToken__application/json__bar.

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:

Configuration Result
<Scope>Global</Scope> mycompany__prod__.

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

Configuration Result
<Scope>Global</Scope>
<CacheKey>
    <KeyFragment>hello</KeyFragment>
    <KeyFragment>world</KeyFragment>
<CacheKey>
mycompany__prod__hello__world.

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

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