General purpose caching

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

You can use policies to store data in a general purpose cache for faster retrieval. Using the following policies, your proxy can store and retrieve cached data at runtime:

• Populate Cache policy to add data to the cache.
• LookupCache policy to access cached data.
• InvalidateCache policy to flush the cache.

Note: This topic describes general purpose caching. For information about response caching, see Response Cache policy, a reference with examples on the Response Cache policy.

These policies are designed for general caching of data used by your proxies.

The sample code in this topic is based on the Outbound OAuth sample proxy on GitHub. This sample uses the cache policy to store an OAuth access token for re-use across multiple outbound calls.

In the following example, an OAuth access token is written to the cache using a PopulateCache policy. The OAuth token is retrieved for subsequent requests by a LookupCache policy. Once the access token expires, JavaScript is used to retrieve a new access token, which is in turn cached by the PopulateCache policy.

Populate the cache

Use the PopulateCache policy to write data to the cache. This example writes an OAuth access token to the cache. For policy reference information, see Populate Cache policy.

Note: Cache keys are limited to a size of 2 KB.

<PopulateCache name="token-cache">
    <!-- The cache to write to. -->
    <CacheResource>mycache</CacheResource>
    <!-- The source of the data, a variable containing the value. -->
    <Source>twitter-translate.apiAccessToken</Source>
    <!-- An enumeration representing a prefix for namespace scope. -->
    <Scope>Exclusive</Scope>
    <!-- A unique pointer (a flow variable value) to the data. Use this later to retrieve it. -->
    <CacheKey>
        <KeyFragment>apiAccessToken</KeyFragment>
        <KeyFragment ref="request.queryparam.client_id"></KeyFragment>
    </CacheKey>
    <!-- Entries placed into the cache with this policy will expire after 600 seconds. -->
    <ExpirySettings>
        <TimeoutInSec>600</TimeoutInSec>
    </ExpirySettings>
</PopulateCache>

Variables can be populated by policies or by code. The Source variable in this example is populated by the following JavaScript call: context.setVariable('twitter-translate.apiAccessToken', getAccessToken());

For more on cache keys, see Working with cache keys.

Lookup cached data

You can retrieve cached values with the LookupCache policy. The following LookupCache policy reads a value from mycache and writes the value to the variable twitter-translate.apiAccessToken. For policy reference information, see LookupCache policy.

<LookupCache name="token-cache">
    <!-- The cache to read from. -->
    <CacheResource>mycache</CacheResource>
    <!-- Where to assign the retrieved value - here, a variable. -->
    <AssignTo>twitter-translate.apiAccessToken</AssignTo>
    <!-- An enumeration representing a prefix for namespace scope. -->
    <Scope>Exclusive</Scope>
    <!-- The unique pointer (a flow variable value) that was used to store the data in the cache. -->

    <CacheKey>
        <KeyFragment>apiAccessToken</KeyFragment>
        <KeyFragment ref="request.queryparam.client_id"></KeyFragment>
    </CacheKey>
</LookupCache>

Invalidate the cache

The cache can be invalidated explicitly by specifying an HTTP header. When a request that contains the specified HTTP header is received, the cache will be flushed. For policy reference information, see InvalidateCache policy.

<InvalidateCache name="InvalidateMyCache">
    <!-- The cache to invalidate. -->
    <CacheResource>test-cache</CacheResource>
    <!-- An enumeration representing a prefix for namespace scope. -->
    <Scope>Exclusive</Scope>
    <!-- Fragments constructing the unique pointer used when 
        the data was put into the cache. -->
    <CacheKey>
        <KeyFragment>apiAccessToken</KeyFragment>
        <KeyFragment ref="request.queryparam.client_id" />
    </CacheKey>
    <PurgeChildEntries>true</PurgeChildEntries>
</InvalidateCache>