API Management caching policies

This article provides a reference for the following API Management policies. For information on adding and configuring policies, see Policies in API Management.

Important

Built-in cache is volatile and is shared by all units in the same region in the same API Management service.

Caching policies

Get from cache

Use the cache-lookup policy to perform cache look up and return a valid cached response when available. This policy can be applied in cases where response content remains static over a period of time. Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

Note

This policy must have a corresponding Store to cache policy.

Policy statement

<cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" caching-type="prefer-external | external | internal" downstream-caching-type="none | private | public" must-revalidate="true | false" allow-private-response-caching="@(expression to evaluate)">
  <vary-by-header>Accept</vary-by-header>
  <!-- should be present in most cases -->
  <vary-by-header>Accept-Charset</vary-by-header>
  <!-- should be present in most cases -->
  <vary-by-header>Authorization</vary-by-header>
  <!-- should be present when allow-private-response-caching is "true"-->
  <vary-by-header>header name</vary-by-header>
  <!-- optional, can repeated several times -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can repeated several times -->
</cache-lookup>

Note

When using vary-by-query-parameter, you might want to declare the parameters in the rewrite-uri template or set the attribute copy-unmatched-params to false. By deactivating this flag, parameters that aren't declared are sent to the back end.

Examples

Example

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none" must-revalidate="true" caching-type="internal" >
            <vary-by-query-parameter>version</vary-by-query-parameter>
        </cache-lookup>
    </inbound>
    <outbound>
        <cache-store duration="seconds" />
        <base />
    </outbound>
</policies>

Example using policy expressions

This example shows how to configure API Management response caching duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive. For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 25:25.

<!-- The following cache policy snippets demonstrate how to control API Management response cache duration with Cache-Control headers sent by the backend service. -->

<!-- Copy this snippet into the inbound section -->
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >
  <vary-by-header>Accept</vary-by-header>
  <vary-by-header>Accept-Charset</vary-by-header>
</cache-lookup>

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the default value of 5 min if none is found  -->
<cache-store duration="@{
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;
  }"
 />

For more information, see Policy expressions and Context variable.

Elements

Name Description Required
cache-lookup Root element. Yes
vary-by-header Start caching responses per value of specified header, such as Accept, Accept-Charset, Accept-Encoding, Accept-Language, Authorization, Expect, From, Host, If-Match. No
vary-by-query-parameter Start caching responses per value of specified query parameters. Enter a single or multiple parameters. Use semicolon as a separator. If none are specified, all query parameters are used. No

Attributes

Name Description Required Default
allow-private-response-caching When set to true, allows caching of requests that contain an Authorization header. No false
caching-type Choose between the following values of the attribute:
- internal to use the built-in API Management cache,
- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external to use external cache if configured or internal cache otherwise.		 No prefer-external
downstream-caching-type This attribute must be set to one of the following values.

- none - downstream caching is not allowed.
- private - downstream private caching is allowed.
- public - private and shared downstream caching is allowed.		 No none
must-revalidate When downstream caching is enabled this attribute turns on or off the must-revalidate cache control directive in gateway responses. No true
vary-by-developer Set to true to cache responses per developer account that owns subscription key included in the request. Yes False
vary-by-developer-groups Set to true to cache responses per user group. Yes False

Usage

This policy can be used in the following policy sections and scopes.

  • Policy sections: inbound
  • Policy scopes: all scopes

Store to cache

The cache-store policy caches responses according to the specified cache settings. This policy can be applied in cases where response content remains static over a period of time. Response caching reduces bandwidth and processing requirements imposed on the backend web server and lowers latency perceived by API consumers.

Note

This policy must have a corresponding Get from cache policy.

Policy statement

<cache-store duration="seconds" cache-response="true | false" />

Examples

Example

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="true | false" vary-by-developer-groups="true | false" downstream-caching-type="none | private | public" must-revalidate="true | false">
            <vary-by-query-parameter>parameter name</vary-by-query-parameter> <!-- optional, can repeated several times -->
        </cache-lookup>
    </inbound>
    <outbound>
        <base />
        <cache-store duration="3600" />
    </outbound>
</policies>

Example using policy expressions

This example shows how to configure API Management response caching duration that matches the response caching of the backend service as specified by the backed service's Cache-Control directive. For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 25:25.

<!-- The following cache policy snippets demonstrate how to control API Management response cache duration with Cache-Control headers sent by the backend service. -->

<!-- Copy this snippet into the inbound section -->
<cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="public" must-revalidate="true" >
  <vary-by-header>Accept</vary-by-header>
  <vary-by-header>Accept-Charset</vary-by-header>
</cache-lookup>

<!-- Copy this snippet into the outbound section. Note that cache duration is set to the max-age value provided in the Cache-Control header received from the backend service or to the default value of 5 min if none is found  -->
<cache-store duration="@{
    var header = context.Response.Headers.GetValueOrDefault("Cache-Control","");
    var maxAge = Regex.Match(header, @"max-age=(?<maxAge>\d+)").Groups["maxAge"]?.Value;
    return (!string.IsNullOrEmpty(maxAge))?int.Parse(maxAge):300;
  }"
 />

For more information, see Policy expressions and Context variable.

Elements

Name Description Required
cache-store Root element. Yes

Attributes

Name Description Required Default
duration Time-to-live of the cached entries, specified in seconds. Yes N/A
cache-response Set to true to cache the current HTTP response. If the attribute is omitted or set to false, only HTTP responses with the status code 200 OK are cached. No false

Usage

This policy can be used in the following policy sections and scopes.

  • Policy sections: outbound
  • Policy scopes: all scopes

Get value from cache

Use the cache-lookup-value policy to perform cache lookup by key and return a cached value. The key can have an arbitrary string value and is typically provided using a policy expression.

Note

This policy must have a corresponding Store value in cache policy.

Policy statement

<cache-lookup-value key="cache key value"
    default-value="value to use if cache lookup resulted in a miss"
    variable-name="name of a variable looked up value is assigned to"
    caching-type="prefer-external | external | internal" />

Example

For more information and examples of this policy, see Custom caching in Azure API Management.

<cache-lookup-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    variable-name="userprofile" />

Elements

Name Description Required
cache-lookup-value Root element. Yes

Attributes

Name Description Required Default
caching-type Choose between the following values of the attribute:
- internal to use the built-in API Management cache,
- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external to use external cache if configured or internal cache otherwise.		 No prefer-external
default-value A value that will be assigned to the variable if the cache key lookup resulted in a miss. If this attribute is not specified, null is assigned. No null
key Cache key value to use in the lookup. Yes N/A
variable-name Name of the context variable the looked up value will be assigned to, if lookup is successful. If lookup results in a miss, the variable will not be set. Yes N/A

Usage

This policy can be used in the following policy sections and scopes.

  • Policy sections: inbound, outbound, backend, on-error
  • Policy scopes: all scopes

Store value in cache

The cache-store-value performs cache storage by key. The key can have an arbitrary string value and is typically provided using a policy expression.

Note

The operation of storing the value in cache performed by this policy is asynchronous. The stored value can be retrieved using Get value from cache policy. However, the stored value may not be immediately available for retrieval since the asynchronous operation that stores the value in cache may still be in progress.

Policy statement

<cache-store-value key="cache key value" value="value to cache" duration="seconds" caching-type="prefer-external | external | internal" />

Example

For more information and examples of this policy, see Custom caching in Azure API Management.

<cache-store-value
    key="@("userprofile-" + context.Variables["enduserid"])"
    value="@((string)context.Variables["userprofile"])" duration="100000" />

Elements

Name Description Required
cache-store-value Root element. Yes

Attributes

Name Description Required Default
caching-type Choose between the following values of the attribute:
- internal to use the built-in API Management cache,
- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external to use external cache if configured or internal cache otherwise.		 No prefer-external
duration Value will be cached for the provided duration value, specified in seconds. Yes N/A
key Cache key the value will be stored under. Yes N/A
value The value to be cached. Yes N/A

Usage

This policy can be used in the following policy sections and scopes.

  • Policy sections: inbound, outbound, backend, on-error
  • Policy scopes: all scopes

Remove value from cache

The cache-remove-value deletes a cached item identified by its key. The key can have an arbitrary string value and is typically provided using a policy expression.

Policy statement


<cache-remove-value key="cache key value" caching-type="prefer-external | external | internal"  />

Example


<cache-remove-value key="@("userprofile-" + context.Variables["enduserid"])"/>

Elements

Name Description Required
cache-remove-value Root element. Yes

Attributes

Name Description Required Default
caching-type Choose between the following values of the attribute:
- internal to use the built-in API Management cache,
- external to use the external cache as described in Use an external Azure Cache for Redis in Azure API Management,
- prefer-external to use external cache if configured or internal cache otherwise.		 No prefer-external
key The key of the previously cached value to be removed from the cache. Yes N/A

Usage

This policy can be used in the following policy sections and scopes .

  • Policy sections: inbound, outbound, backend, on-error
  • Policy scopes: all scopes

Next steps

For more information working with policies, see: