---
schema_version: "1"
id: 0389ebce11c978f796e44737a22459020e4f84cb7f42032c1955b5da84d7663e
title: HTTP Caching Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-http-caching.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-http-caching
source_site: docs.mulesoft.com
content_type: documentation
content_hash: ef21d045f5a0b81b63b2c2ec1985c1a426086b423f11d7bbd5ac845adcd5055b
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: http caching, api gateway, flex gateway, gateway, policy
---

# HTTP Caching Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>HTTP caching</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Caches HTTP responses from an API implementation</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Quality of Service</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.0.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/http-caching-release-notes">HTTP caching</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy</p></td></tr></tbody></table>

## Summary

The HTTP Caching policy enables you to cache HTTP responses for reuse. Caching these responses
speeds up the response time for user requests and reduces the load on the backend. For example, if
your backend exposes an endpoint for which the responses to requests are not likely to change, you
can reuse the HTTP responses and bypass the backend request processing by using the HTTP Caching
policy.

Policies applied after the HTTP Caching policy in the policy order are not applied to responses
served from the cache. For example, a rate limiting policy applied after the HTTP Caching policy
only limits the responses served by the upstream service but not the responses served by the cache.
Apply all policies needed for the cached response before the HTTP Caching policy.

For Self-Managed Gateways, HTTP caching requires that you
[configure shared storage](#configure-shared-storage-for-self-managed-gateway). For Managed
Gateways, Omni Replica shares the cache with each other directly. To learn more about the Managed
Gateway architecture, see
[Managed Omni Gateway High Availability and Disaster Recovery Deployments](https://docs.mulesoft.com/gateway/1.13/gateway-architecture-managed-dr-ha).

> [!NOTE] The HTTP Caching policy does not support MCP and A2A server instances.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: http-caching-flex config: httpCachingKey: <string> // REQUIRED, default:
"#\[attributes.requestPath\]" maxCacheEntries: <int> // REQUIRED, default: 10000 ttl: <int> //
REQUIRED, default: 600 useHttpCacheHeaders: <bool> // REQUIRED, default: true invalidationHeader:
<string> // OPTIONAL, default: "" requestExpression: <string> // OPTIONAL, default:
"#\[attributes.method == 'GET' or attributes.method == 'HEAD'\]" responseExpression: <string> //
OPTIONAL, default: "#\[\[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501\] contains
attributes.statusCode\]" distributed: <bool> // REQUIRED, default: false persistCache: <bool> //
REQUIRED, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>httpCachingKey</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>#[attributes.requestPath]</code></p></div></div></td><td><div><div><p>A DataWeave expression</p></div></div></td></tr><tr><td><div><div><p><code>maxCacheEntries</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>10000</p></div></div></td><td><div><div><p>Specifies the maximum number of entries that can be stored in the cache at any given time</p></div></div></td></tr><tr><td><div><div><p><code>ttl</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>600</p></div></div></td><td><div><div><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache</p></div></div></td></tr><tr><td><div><div><p><code>useHttpCacheHeaders</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>true</p></div></div></td><td><div><div><p>Enables the use of Cache-Control header directives</p></div></div></td></tr><tr><td><div><div><p><code>invalidationHeader</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty string</p></div></div></td><td><div><div><p>A string specifying the header used to invalidate a single entry or the entire cache</p></div></div></td></tr><tr><td><div><div><p><code>requestExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>responseExpression</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></div></div></td><td><div><div><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true)</p></div></div></td></tr><tr><td><div><div><p><code>distributed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to be distributed among different nodes in a cluster</p></div></div></td></tr><tr><td><div><div><p><code>persistCache</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Configures the cache to persist between different restarts of the replica</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

#### Resource Configuration Example

```yaml
- policyRef:
    name: http-caching-flex
  config:
    httpCachingKey: "#[attributes.requestPath]"
    maxCacheEntries: 10000
    ttl: 500
    useHttpCacheHeaders: false
    requestExpression: "#[attributes.method == 'GET' or attributes.method == 'HEAD']"
    responseExpression:
      "#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]"
```

#### Configure Shared Storage for Self-Managed Gateway

Self-Managed Gateways require you to configure shared storage for distributed caching. Configure
either [distributed shared storage](https://docs.mulesoft.com/gateway/1.13/conn-distributed-shared-storage-config) or
[Redis shared storage](https://docs.mulesoft.com/gateway/1.13/conn-shared-storage-config).

\--- apiVersion: gateway.mulesoft.com/v1alpha1 kind: Configuration metadata: name:
api-shared-storage spec: sharedStorage: objectStore: url:
distributed://0.0.0.0:30001?join=flex.hostname.com:30001

---

apiVersion: gateway.mulesoft.com/v1alpha1 kind: PolicyBinding metadata: name: ingress-http-caching
spec: targetRef: kind: ApiInstance name: ingress-http policyRef: kind: Extension name:
http-caching-flex config: httpCachingKey: "#\[attributes.method ++ attributes.requestPath\]"
useHttpCacheHeaders: true maxCacheEntries: 100 ttl: 600 distributed: true persistCache: true
invalidationHeader: AGW-CACHE-CONTROL

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th><th><strong>Required?</strong></th></tr></thead><tbody><tr><td><p>HTTP Caching Key</p></td><td><p>A DataWeave expression. Default value: <code>#[attributes.requestPath]</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Maximum Cache Entries</p></td><td><p>Specifies the maximum number of entries that can be stored in the cache at any given time. Default value: <code>10000</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Entry Time To Live</p></td><td><p>Specifies the amount of time (in seconds) after which a single entry expires from the cache. Default value: <code>600</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Distributed</p></td><td><p>Configures the cache to be distributed among different nodes in a cluster. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Persistent Cache</p></td><td><p>Configures the cache to persist between different restarts of the Omni Gateway instance. Default value: <code>false</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Follow HTTP Caching directives</p></td><td><p>Enables the use of Cache-Control header directives. Default value: <code>true</code></p></td><td><p>Yes</p></td></tr><tr><td><p>Invalidation Header</p></td><td><p>Name of the header used to invalidate a single entry or the entire cache.</p></td><td><p>No</p></td></tr><tr><td><p>Conditional Request Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which requests are to be cached (caches the response only if the condition is true). Default value: <code>#[attributes.method == 'GET' or attributes.method == 'HEAD']</code></p></td><td><p>No</p></td></tr><tr><td><p>Conditional Response Caching Expression</p></td><td><p>The DataWeave expression that is used to decide which responses are to be cached (caches the response only if the condition is true). Default value: <code>#[[200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501] contains attributes.statusCode]</code></p></td><td><p>No</p></td></tr></tbody></table>

## How This Policy Works

When an HTTP request reaches an endpoint, what happens next depends on whether that request does not
already exist in cache (a cache miss) or whether it does (a cache hit).

### Cache Miss

1.  The client (user) sends a request to the API.

2.  The request proceeds through other policies in the policy chain before reaching the HTTP Caching
    policy.

3.  The HTTP Caching policy checks if the request is cached. If not, the cache-miss process is
    initiated.

4.  The request continues throughout the chain of other remaining policies.

5.  The request reaches the backend and completes all required processing.

6.  The backend responds and the response travels back through the policy chain.

7.  The response reaches the HTTP Caching policy.

8.  The HTTP Caching policy caches the response for later reuse if it hasn’t already been cached.

9.  The response continues through the remaining policies in the policy chain.

10. The response is returned to the client.

### Cache Hit

1.  The client (user) sends a request to the API.

2.  The request crosses other policies before reaching the HTTP Caching policy.

3.  The HTTP Caching policy verifies that the request is already in the cache.

4.  The [key](#key) is found in the cache and the stored response is returned.

5.  The response continues through the rest of the policy chain until it reaches the last one.

6.  The cached response is returned to the client.

### Stored Entries

_Stored entries_ are the cached HTTP responses. The cache can store any serializable data or input
streams of up to 1 MB. If that value is surpassed, then the reading stops and the value is not
stored in such a case.

### HTTP Caching Key

The cache works as a dictionary, where each response stored in the cache is associated with a string
called _key_. For example, the expression #\[attributes.headers\['key'\]\] uses the header called
`key` as the entry key. You can use any DataWeave expression that returns a string, including
[predefined DataWeave variables](https://docs.mulesoft.com/gateway/1.13/policies-dataweave-support#available-predefined-variables).

### Cache Size and Entry Expiration

The cache can hold a specified number of entries at any given time. You can configure this number
using the `Maximum Cache Entries` property. Each stored entry is held in the cache memory for a
specific period of time, after which the entry expires and must be processed again. This expiration
time is called _time to live_ (TTL).

Another condition that can trigger the expiration of an entry is when the cache reaches the maximum
number of items that it can store. When this scenario occurs, the entry is removed by using the FIFO
(First-In First-Out) criteria. This means that the earliest entry to reach the cache is removed,
even though it hasn’t reached the TTL value yet.

### Distributed Cache

Each entry in the cache can be shared between different nodes in a cluster or between several
workers in Runtime Manager using the `Distributed` option (see table). If this option is not
enabled, then each node is assigned its own cache memory.

### Persistent Cache

A persistent cache enables the stored entries in the cache to persist if the Omni Replica is
restarted.

When you upgrade a version of the instance that has the HTTP Caching policy configured to use the
persistent store, the policy tries to maintain the entries stored by the previous version. However
in a worst-case scenario, the entries in the cache are invalidated and the cache is re-populated
when new requests arrive. This manipulation of the entries in the cache occurs automatically and is
invisible to the user.

## HTTP Caching Directives

To obtain more control over the cache, the HTTP Caching policy interprets some of the HTTP
directives from the [RFC-7234](https://tools.ietf.org/html/rfc7234) protocol by taking the following
headers into account:

- `Cache-Control`

- `Expires`

- `Date`

- `Age`

### Cache-Control

The `Cache-Control` header can exist either in the request or in the response. Possible values for
the header, which can be combined separated by commas, include:

- In requests:

  - `no-cache`

The response is not searched for, but is directly stored in the cache.

- `no-store`

The response is not stored in the cache. However, if the response is already present in the cache,
the policy returns the response.

- In responses:

  - `no-store`, `no-cache`, `private`

For each value, the response is not stored in the cache.

- `max-age=<integer>`, `s-maxage=<integer>`

The `<integer>` placeholder must be replaced with a valid integer that indicates the time (in
seconds) for which the response can remain in the cache. If both parameters are defined, `s-maxage`
takes precedence over `max-age`.

If a global time-to-live (TTL) value is also defined for the policy, these header values override
the global TTL configured in the policy if the time specified in the headers is less than the global
TTL.

### Expires

If present, this header specifies the date by which the entry in the cache expires. If you specify
the `max-age` directive or `s-maxage` directive, this header is ignored. You must define the header
value as stated in [RFC-1123](https://tools.ietf.org/html/rfc1123).

### Date

The `date` header, as defined per [RFC-1123](https://tools.ietf.org/html/rfc1123), specifies the
date and time when the response is created. If not defined, the `date` header is added with the time
when the request was received. This header is used in conjunction with the values defined in the
`max-age` and `s-maxage` directives of the Cache-Control header.

### Age

The `age` header indicates the time (in seconds) elapsed since the origin of the cached response
specified in the date header. This header is calculated by the policy and added to each response
that is retrieved from the cache.

The expiration time is calculated using the `cache-control`, `date`, and `expires` headers. However,
if the resulting expiration time exceeds the one imposed by the TTL value of the entry, the cache
entry expires anyway.

### Invalidate

The `invalidate` header, if configured in the HTTP Caching policy, invalidates the entries in the
cache, thereby causing the request to be processed again. You specify the name of the header in the
Invalidation Header configuration to turn on the option. The value of the header can take only one
of the following options: `invalidate`

This option invalidates the entry whose key matches the current request. `invalidate-all` This
option invalidates all the entries from the cache.

For example, imagine that the following values are configured in the policy for the request:

- `HTTP Caching Key`: "#\[attributes.requestPath\]"

- `Invalidation header`: "myInvalidationHeader"

The following command invalidates the entry with key “/my/policy" from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate”`

The following request invalidates all entries from the cache:

`curl [http://<MyAppURL>/my/policy](http://\<MyAppURL\>/my/policy) -H “myInvalidationHeader:invalidate-all”`

## Conditional Caching

Conditional caching enables you to configure a set of conditions that must be met before entries are
stored in the cache. If none of the conditional caching parameters are configured, the cache stores
the responses for every incoming request. If configured, parameters are evaluated for each request
to determine whether the response of the current request must be stored.

For conditional request expressions, only the responses for incoming requests with HTTP methods
`GET` or `HEAD` are cached by default. For conditional response expressions, only status codes
specified by [RFC-7231](https://tools.ietf.org/html/rfc7231#section-6.1) are cached by default.

For more information about the default values, see [Configuring Policy Parameters](#cpp).

## FAQ

**What happens when the evaluation of the key results in any error?**

If the evaluation of the expression for a particular request results in an error, the policy does
not take effect and the request continues to the next receptor in the policy chain.

**Can I store only part of the response with this policy?**

No, but you can apply a policy before this one and transform the response to something else.

**What happens if one parameter is configured to search for the response in the cache and the other
parameter is configured for the opposite action?**

This is the same as configuring the response to be stored in the cache when there is a no-store
directive in the Cache-Control header.

In this situation, the response isn’t stored. You must configure both the Cache-Control header and
the cache to be able to store and search for the response in the cache.

**What happens if I do not define some of the optional parameters?**

If you have not configured the `invalidation` header, you cannot invalidate the cache in a request.
Additionally, if you have not configured the request expression or response expression, the cache is
used for all requests and all the responses are stored in the cache (expression #\[true\]).

**Can I modify the Invalidation header values?**

No, you can modify only the header name.