Get from cache

  • Article

APPLIES TO: All API Management tiers

Use the cache-lookup policy to perform cache lookup 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.

Important

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

Tip

To help you configure this policy, the portal provides a guided, form-based editor. Learn more about how to set or edit API Management policies.

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 be repeated -->
  <vary-by-query-parameter>parameter name</vary-by-query-parameter>
  <!-- optional, can be repeated -->
</cache-lookup>

Attributes

Attribute Description Required Default
allow-private-response-caching When set to true, allows caching of requests that contain an Authorization header. Policy expressions are allowed. 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.

Policy expressions aren't allowed.		 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.

Policy expressions are 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. Policy expressions are allowed. No true
vary-by-developer Set to true to cache responses per developer account that owns subscription key included in the request. Policy expressions are allowed. Yes false
vary-by-developer-groups Set to true to cache responses per user group. Policy expressions are allowed. Yes false

Elements

Name Description Required
vary-by-header Add one or more of these elements to 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 Add one or more of these elements to start caching responses per value of specified query parameters. Enter a single or multiple parameters. Use semicolon as a separator. No

Usage

Usage notes

  • API Management only performs cache lookup for HTTP GET requests.
  • 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 backend.
  • This policy can only be used once in a policy section.

Examples

Example with corresponding cache-store policy

<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 backend service's Cache-Control directive.

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

Next steps

For more information about working with policies, see: