cache.md

description
This page provides the technical details of the Cache policy

Cache

Overview

You can use the cache policy to cache upstream responses (content, status and headers) to eliminate the need for subsequent calls to the back end.

This policy is based on a cache resource, which aligns the underlying cache system with the API lifecycle (stop/start).

Consumers can bypass the cache by adding a cache=BY_PASS query parameter or by providing a X-Gravitee-Cache=BY_PASS HTTP header.

{% hint style="info" %} Make sure to define your Cache resource

If no cache resource is defined for the policy, or it is not well configured, the API will not be deployed. The resource name is specified in the policy configuration cacheName. {% endhint %}

Functional and implementation information for the cache policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Changelogs

Examples

{% hint style="warning" %} This policy can only be applied to v2 APIs. It cannot be applied to v4 message APIs or v4 proxy APIs. {% endhint %}

{% tabs %} {% tab title="Proxy API example" %} The key used to store elements in cache can use the Gravitee Expression Language to provide a dynamic value.

Key based on the productId query parameter:

"key": "{#request.params['productId']}"

Key based on the api-key of the consumer:

"key": "{#request.headers['X-Gravitee-Api-Key']}"

Key based on an API’s property and a query parameter:

"key": "{#properties['siteID']}-{#request.params['productId']}"

{% endtab %} {% endtabs %}

Configuration

Sample policy configuration:

{% code title="Sample Configuration" %}

"cache": {
    "cacheName": "policy-cache",
    "key": "{#request.params['productId']}",
    "timeToLiveSeconds": 600,
    "useResponseCacheHeaders": false,
    "scope": "APPLICATION",
    "methods": ["POST"],
    "responseCondition": "{#upstreamResponse.status == 201}"
}

{% endcode %}

Gateway configuration (gravitee.yml)

  policy:
    cache:
      serialization: text # default value or "binary" (not compatible with Redis)

The policy.cache.serialization allows configuration of the serialization format of the cache.

The default value is text, but you can also use binary to use a binary serialization format. The binary serialization format is not compatible with the Redis cache resource.

Phases

The phases checked below are supported by the cache policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	false
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

You can configure the cache policy with the following options:

Property	Required	Description	Type	Default
cacheName	true	The cache resource used to store the element	string
key	false	The key used to store the element (supports EL)	string
timeToLiveSeconds	true	Time to live of the element put in cache (default is 10 minutes)	integer	600
methods	true	Select which method you want to cache	array of strings	[GET, OPTIONS, HEAD]
responseCondition	false	Add an extra condition (with Expression Language) based on the response to activate cache. For example use {#upstreamResponse.status == 200} to only cache 200 responses status. By default, all 2xx are cached.	string
useResponseCacheHeaders	false	Time to live based on 'Cache-Control' and / or 'Expires' headers from backend response	boolean	false
scope	true	Cached response can be set for a single consumer (application) or for all applications. WARNING: Please be aware that by using an "API" scope, data will be shared between all consumers!	API / APPLICATION	APPLICATION

Compatibility matrix

The following is the compatibility matrix for APIM and the cache policy:

Plugin Version	Supported APIM versions
1.x	3.x
2.x	4.0+

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-cache/blob/master/CHANGELOG.md" %}