—Rate this article—
 

LookupCache policy

ResponseCache policy icon LookupCache policy

About | Element reference | Usage notes

What

Configures how cached values should be retrieved at runtime.

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Element reference

The following lists the elements you can configure on this policy.

<LookupCache async="false" continueOnError="false" enabled="true" name="Lookup-Cache-1">
    <DisplayName>Lookup Cache 1</DisplayName>
    <FaultRules/>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <AssignTo>flowVar</AssignTo>
</LookupCache>

A shared cache is included by default. To use the shared cache, omit the <CacheResource> element in this policy configuration.

For more about the underlying data store, see Why Use a Cache?. For more about configuring caches, see Manage caches for an environment.

<LookupCache> attributes

Attribute Description Default Presence
async

true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

true to specify that flow execution should continue on a failure. Default is false.

Most policies are expected to return an error when a failure occurs (for example, when a quota is exceeded).

false Optional
name

Specifies the name of the policy, which is referenced in step elements to attach the policy to a flow. Characters you can use in the name are restricted to: A-Z0-9._\-$ %.

  Required

<AssignTo> element

Specifies the variable where the cache entry is assigned after it has been retrieved from the cache. The variable must be writable.

<AssignTo>variable_to_receive_cached_value</AssignTo>

Default:

N/A

Presence:

Required

Type:

String

<CacheKey> element

Configures a unique pointer to a piece of data stored in the cache.

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

Default:

N/A

Presence:

Required

Type:

N/A

<CacheKey> constructs the name of each piece of data stored in the cache.

At runtime, <KeyFragment> values are prepended with either the <Scope> element value or <Prefix> value. For example, the following results in a cache key of UserToken__apiAccessToken__<value_of_client_id>:

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

You use the <CacheKey> element in conjunction with <Prefix> and <Scope>. For more information, see Working with cache keys.

<CacheResource> element

Specifies the cache where messages should be stored.

Omit this element completely if this policy (and your corresponding PopulateCache and InvalidateCache policies) is using the included shared cache.

<CacheResource>cache_to_use</CacheResource>

Default:

N/A

Presence:

Optional

Type:

String

For more about configuring caches, see Manage caches for an environment.

<CacheKey>/<KeyFragment> element

Specifies a value that should be included in the cache key, creating a namespace for matching requests to cached responses.

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

Default:

N/A

Presence:

Optional

Type:

N/A

This can be a key (a static name that you provide) or a value (a dynamic entry set by referencing a variable). All specified fragments combined (plus the prefix) are concatenated to create the cache key.

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

You use the <KeyFragment> element in conjunction with <Prefix> and <Scope>. For more information, see Working with cache keys.

Attributes

Attribute Type Default Required Description
ref string   No

The variable from which to get the value. Should not be used if this element contains a literal value.

<CacheKey>/<Prefix> element

Specifies a value to use as a cache key prefix.

<Prefix>prefix_string</Prefix>

Default:

N/A

Presence:

Optional

Type:

String

Use this value instead of <Scope> when you want to specify your own value rather than a <Scope> -enumerated value. If defined, <Prefix> prepends the cache key value for entries written to the cache. A <Prefix> element value overrides a <Scope> element value.

You use the <Prefix> element in conjunction with <CacheKey> and <Scope>. For more information, see Working with cache keys.

<Scope> element

Enumeration used to construct a prefix for a cache key when a <Prefix> element is not provided in the <CacheKey> element.

<Scope>scope_enumeration</Scope>

Default:

"Exclusive"

Presence:

Optional

Type:

String

The <Scope> setting determines a cache key that is prepended according to the <Scope> value. For example, a cache key would take the following form when scope is set to Exclusive : orgName__envName__applicationName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

If a <Prefix> element is present in <CacheKey>, it supercedes a <Scope> element value. Valid values include the enumerations below.

You use the <Scope> element in conjunction with <CacheKey> and <Prefix>. For more information, see Working with cache keys.

Acceptable values

Global

Cache key is shared across all API proxies deployed in the environment. Cache key is prepended in the form  orgName __ envName __.

If you define a <CacheKey> entry with the <KeyFragment> apiAccessToken and a <Global> scope, each entry is stored as orgName__envName__apiAccessToken, followed by the serialized value of the access token. For an API proxy deployed in an environment called 'test' in an organization called 'apifactory', access tokens would be stored under the following cache key: apifactory__test__apiAccessToken.

Application

API proxy name is used as the prefix.

Cache key is prepended in the form orgName__envName__applicationName.

Proxy

ProxyEndpoint configuration is used as the prefix.

Cache key is prepended in the form orgName__envName__applicationName__deployedRevisionNumber__proxyEndpointName .

Target

TargetEndpoint configuration is used as the prefix.

Cache key prepended in the form orgName__envName__applicationName__deployedRevisionNumber__targetEndpointName .

Exclusive

Default. This is the most specific, and therefore presents minimal risk of namespace collisions within a given cache.

Prefix is one of two forms:

  • If the policy is attached to the ProxyEndpoint flow, prefix is of the form ApiProxyName_ProxyEndpointName.
  • If the policy is attached at TargetEndpoint, prefix is of the form ApiProxyName_TargetName.

Cache key prepended in the form orgName__envName__applicationName__deployedRevisionNumber__proxyNameITargetName

For example, the full string might look like this:

apifactory__test__weatherapi__16__default__apiAccessToken
.

Flow variables

Flow variables can be used to configure dynamic runtime behavior for policies and flows, based on HTTP headers or message content, or the context available in the Flow. For more information about flow variables, see Variables reference.

The following predefined Flow variables are available after you customize the behavior of the cache you define in a LookupCache policy.

Variables Type Permission Description
lookupcache.<policy-name>.cachename String Read-Only Returns the cache name used in the policy.
lookupcache.<policy-name>.cachekey String Read-Only Returns the key used.
lookupcache.<policy-name>.cachehit Boolean Read-Only True if the policy execution is successful.
lookupcache.<policy-name>.assignto String Read-Only Returns the variable to which cache is assigned.

Usage notes

Use this policy for general-purpose caching. At runtime, the LookupCache policy retrieves a value from the cache, assigning the value to the variable you specify with the AssignTo element. It looks for the value based on a cache key created through configuration that combines the CacheKey and Scope elements. In other words, to retrieve a particular value added to the cache by a PopulateCache policy, your LookupCache policy must have cache key-related elements configured in the same way.

General purpose caching with the Populate Cache policy, LookupCache policy, and InvalidateCache policy uses either a cache you configure or a shared cache that's included by default. In most cases, the underlying shared cache should meet your needs. To use this cache, simply omit the <CacheResource> element.

For more about configuring caches, see Manage caches for an environment. For more about the underlying data store, see Why Use a Cache?.

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