Send Docs Feedback

InvalidateCache policy

What

Configures how the cached values should be purged from the cache.

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.

<InvalidateCache async="false" continueOnError="false" enabled="true" name="policy-name">
    <DisplayName>Policy Name</DisplayName>
    <FaultRules>rules_for_fault_handling</FaultRules>
    <Properties>property_elements</Properties>
    <CacheKey>
        <Prefix>prefix_string</Prefix>
        <KeyFragment ref="variable_reference"/>
        <KeyFragment>fragment_string</KeyFragment>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource>cache_to_use</CacheResource>
    <Scope>scope_enumeration</Scope>
    <CacheContext>
        <APIProxyName>application_that_added_the_entry</APIProxyName>
        <ProxyName>proxy_for_which_data_was_cached</ProxyName>
        <TargetName>endpoint_for_which_data_was_cached</TargetName>
    </CacheContext>
    <PurgeChildEntries>true_to_purge_all_child_entries</PurgeChildEntries>
</InvalidateCache>

<InvalidateCache> attributes

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

Note: This attribute does not make the policy execute asynchronously.

When set to true, policy execution is offloaded to a different thread, leaving the main thread free to handle additional requests. When the offline processing is complete, the main thread comes back and finishes handling the message flow. In some cases, setting async to true improves API proxy performance. However, overusing async can hurt performance with too much thread switching.

To use asynchronous behavior in API proxies, see JavaScript callouts.

false Optional

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<CacheContext>/<APIProxyName> element

Specifies the name of the application that added the cache entry.

<APIProxyName>application_that_added_the_entry</APIProxyName>

Attributes

Attribute Description Default Presence Type
ref Variable with the application name. N/A Optional String
 

<CacheContext> element

Specifies how to construct a cache key when a Prefix element value is not specified, or to clear cache entries added by another API proxy.

<CacheContext>
  <APIProxyName ref="variable_name">application_that_added_the_entry</ApplicationName>
  <TargetName ref="variable_name">endpoint_for_which_data_was_cached</TargetName>
  <ProxyName ref="variable_name">proxy_for_which_data_was_cached</ProxyName>
</CacheContext>

Used to construct the CacheKey. Values for APIProxyName, ProxyName, and TargetName are mandatory when a CacheKey prefix (that is, a custom prefix) is not used to clear cache entries added by another API proxy.

<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 LookupCache 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 Creating and editing an environment cache.

<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 Description Default Presence Type
ref The variable from which to get the value. Should not be used if this element contains a literal value. N/A Optional String
 

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

<CacheContext>/<ProxyName> element

Specifies the name of the proxy for which the data was cached.

<ProxyName>proxy_for_which_data_was_cached</ProxyName>

Default:

N/A

Presence:

Optional

Type:

String

Attributes

Attribute Description Default Presence Type
ref The variable from which to get the value. Should not be used if this element contains a literal value. N/A Optional String
 

<PurgeChildEntries> element

true to purge cache entries that share the value set by a <KeyFragment> element configured for this policy. Values in other parts of the cache key, such as in <Prefix> elements, are not considered.

Note that the <KeyFragment> element must be specified. If it is not, setting true for <PurgeChildEntries> could result in purging all entries in the cache.

Invalidating all of the cache entries of the same key fragement value can be a useful way to purge multiple related entries at once.

<PurgeChildEntries>true_to_purge_child_entries</PurgeChildEntries>

Default:

false

Presence:

Optional

Type:

Boolean

<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

Scope Value Description
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
.

<CacheContext>/<TargetName> element

Specifies the name of the target endpoint for which the data was cached.

<TargetName>endpoint_for_which_data_was_cached</TargetName>

Default:

N/A

Presence:

Optional

Type:

String

Attributes

Attribute Description Default Presence Type
ref The variable from which to get the value. Should not be used if this element contains a literal value. N/A Optional String
 

Usage notes

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 Creating and editing an environment cache. For more about the underlying data store, see Why Use a Cache?.

Help or comments?