--- name: azion-configure-cache-policies-for-an-application description: >- Set how long an object stays cached, bypass the cache for a path, and forward the origin's Set-Cookie header to users. --- # Configure cache policies for an application From Azion Console or the API, you set how long an object stays cached, bypass the cache for a path, and forward the origin's `Set-Cookie` header. A cache setting carries the cache policy, and a [Rules Engine](/en/documentation/platform/applications/rules-engine/) rule applies it to the requests you choose. To vary a cached object by a query string argument or by a cookie, refer to [Configure Advanced Cache Key](/en/documentation/guides/application-performance/cache-and-purge/advanced-cache-key/). --- ## Prerequisites ### Console - An application. To create one, refer to [Applications quickstart](/en/documentation/platform/applications/quickstart/). - Access to Azion Console. Refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - Application Accelerator can generate usage-related costs. For the rates, refer to [Pricing](/en/documentation/fundamentals/pricing/#application-accelerator). ### API - An application. To create one, refer to [Applications quickstart](/en/documentation/platform/applications/quickstart/). - Access to Azion Console. Refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - A personal token. To create one, refer to [Personal tokens](/en/documentation/guides/platform/account-and-billing/personal-tokens/). - Application Accelerator can generate usage-related costs. For the rates, refer to [Pricing](/en/documentation/fundamentals/pricing/#application-accelerator). --- ## Turn on Application Accelerator A cache setting needs no module, and any application can carry one. [Application Accelerator](/en/documentation/platform/applications/#application-accelerator) is required for a **Max Age** below 60 seconds, for cache variation, and for the **Bypass Cache** and **Forward Cookies** behaviors. The module is off by default. To turn it on: 1. **Open the application** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**. 2. **Turn on the module** On the **Main Settings** tab, in the **Modules** section, turn on **Application Accelerator**. 3. **Select Save** The application runs with Application Accelerator. Its cache settings accept a **Max Age** below 60 seconds, and **Bypass Cache** and **Forward Cookies** become available in **Rules Engine**. --- ## Set the cache TTL for a path A cache setting holds the time-to-live (TTL) the browser applies and the TTL Azion applies. To create one: 1. **Open the Cache Settings tab** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**, then go to the **Cache Settings** tab. 2. **Select + Cache** 3. **Name the cache setting** In **Name**, enter a name that identifies the setting. For example: `/target-uri - Cache TTL`. 4. **Set the browser cache** Under **Browser Cache**, select *Override cache settings* and set the maximum age in seconds. 5. **Set Max Age** Under **Cache**, select *Override cache behavior* and set **Max Age** to the number of seconds Azion keeps the object. 6. **Select Save** The cache setting appears in the **Cache Settings** tab. The same setting can also vary the cached object by query string or by cookie, which is the [Advanced Cache Key](/en/documentation/platform/applications/cache/cache-settings/#application-accelerator) feature. A cache setting takes effect only when a rule applies it. To apply this one to the `/target-uri` path: 1. **Go to the Rules Engine tab** 2. **Select + Rule** 3. **Name the rule** Enter a name for the rule. For example: `/target-uri - Cache TTL`. 4. **Select Request Phase** 5. **Select the variable in the Criteria section** In the **Criteria** section, select the `${uri}` variable. 6. **Select starts with as the comparison operator** 7. **Enter the argument** Enter `/target-uri` as the argument. 8. **In the Behaviors section, select Set Cache Policy** 9. **Select the cache setting you created** 10. **Select Save** Requests whose URI starts with `/target-uri` carry the cache setting, at both the browser TTL and the Azion TTL you set. A new rule takes a few minutes to propagate. --- ## Bypass the cache for a path **Bypass Cache** stops Azion from caching the origin response for the requests a rule matches. To create the rule: 1. **Go to the Rules Engine tab** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**, then go to the **Rules Engine** tab. 2. **Select + Rule** 3. **Name the rule** Enter a name for the rule. For example: `/target-uri - Bypass Cache`. 4. **Select Request Phase** 5. **Select the variable in the Criteria section** In the **Criteria** section, select the `${uri}` variable. 6. **Select starts with as the comparison operator** 7. **Enter the argument** Enter `/target-uri` as the argument. 8. **In the Behaviors section, select Bypass Cache** 9. **Select Save** Requests whose URI starts with `/target-uri` reach the origin, and Azion stores no response for them. A new rule takes a few minutes to propagate. > **Note** > > **Bypass Cache** affects only the cache on Azion, not the browser cache. The browser cache comes from the cache setting that **Set Cache Policy** applies. For more information, refer to [Bypass Cache](/en/documentation/platform/applications/rules-engine/#bypass-cache). For the difference between **Bypass Cache** and a **Max Age** of `0` seconds, refer to [Cache variation](/en/documentation/platform/applications/application-accelerator/cache-variation/). --- ## Bypass the cache for a path with the API **Bypass Cache** can also be set with the API, by sending a rule with a `bypass_cache` behavior. The example bypasses the cache on `/api/`, with a rule named `cdn - api pass-through`. Replace each value with your own. To create the bypass rule: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//request_rules \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "cdn - api pass-through", "active": true, "criteria": [[{ "variable": "${uri}", "conditional": "if", "operator": "starts_with", "argument": "/api/" }]], "behaviors": [{ "type": "bypass_cache" }] }' ``` The API answers `202` with a `state` of `pending` and the rule as it was stored. Requests whose URI starts with `/api/` reach the origin, and Azion stores no response for them. A new rule takes a few minutes to propagate. To confirm the rule, request a path it matches with the `Pragma: azion-debug-cache` header: ```bash curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/api/status ``` The response carries `x-cache: BYPASS`. For how to read the header, refer to [Check the cache status of a response](/en/documentation/guides/application-performance/cache-and-purge/check-page-cache-time/). The [Accelerate websites and APIs with a CDN](/en/documentation/use-cases/improve-performance-and-reliability/accelerate-websites-and-apis-with-a-cdn/) use case uses the values of this example. These checks confirm the [Accelerate websites and APIs with a CDN](/en/documentation/use-cases/improve-performance-and-reliability/accelerate-websites-and-apis-with-a-cdn/) use case. --- ## Forward cookies from the origin to the user **Forward Cookies** sends the origin's `Set-Cookie` header to users, including on a cache hit. To create the rule: 1. **Go to the Rules Engine tab** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**, then go to the **Rules Engine** tab. 2. **Select + Rule** 3. **Name the rule** Enter a name for the rule. For example: `/target-uri - Forward Cookies`. 4. **Select Request Phase** 5. **Select the variable in the Criteria section** In the **Criteria** section, select the `${uri}` variable. 6. **Select starts with as the comparison operator** 7. **Enter the argument** Enter `/target-uri` as the argument. 8. **In the Behaviors section, select Forward Cookies** 9. **Select Save** Requests whose URI starts with `/target-uri` return the origin's `Set-Cookie` header to the user. The forwarded header can carry session cookies. To stop a user from receiving the session cookies of another user: 1. **Go to the Cache Settings tab** 2. **Select + Cache** 3. **Name the cache setting** In **Name**, enter a name that identifies the setting. For example: `/target-uri - Private cookies`. 4. **Denylist the session cookies** Under **Application Accelerator**, open **Cache vary by Cookies** and set **Behavior** to *Denylist*. 5. **Enter the cookie names** Add each session cookie to the list of cookie names. 6. **Select Save** The cache setting appears in the **Cache Settings** tab, and it keeps the listed cookies out of the cache key. To apply that cache setting to the rule that forwards the cookies: 1. **Go to the Rules Engine tab** 2. **Select the rule** Select the `/target-uri - Forward Cookies` rule. 3. **In the Behaviors section, select + Behavior** 4. **Select Set Cache Policy** 5. **Select the cache setting** Select the `/target-uri - Private cookies` cache setting. 6. **Select Save** The rule forwards the origin's `Set-Cookie` header and applies the cache setting. A rule change takes a few minutes to propagate. The same rule can also carry the **Bypass Cache** behavior. --- ## Cache a set of paths only for visitors without a session A rule can hold several criteria. In a group, each criterion after the first joins the one before it with **And** or **Or**, and groups join with **And**, so a request matches only when it meets every group. The rule in this section joins its two paths with **Or** in one group and checks the cookie in a second group. It caches two catalog paths only for requests that carry no session cookie, so a signed-in visitor never receives a shared copy. The example uses `/products/` and `/category/` for the paths and `session_id` for the cookie the origin sets when a session starts. Replace each one with your own. The cache setting keeps a page for 600 seconds on Azion and overrides the browser cache to `0` seconds, because a copy in the browser cannot be purged. ### Console Create a cache setting named `storefront-catalog`, as [Set the cache TTL for a path](#set-the-cache-ttl-for-a-path) shows, with a browser maximum age of `0` and a **Max Age** of `600`. To create the rule that applies it: 1. **Go to the Rules Engine tab** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**, then go to the **Rules Engine** tab. 2. **Select + Rule** 3. **Name the rule** Enter `storefront - catalog cache`. 4. **Select Request Phase** 5. **Match the catalog paths** In the **Criteria** section, set the first criterion to `${uri}` *starts with* `/products/`. Add a second criterion joined by **Or**: `${uri}` *starts with* `/category/`. 6. **Exclude visitors with a session** Add a second criteria group with one criterion: `${cookie_session_id}` *does not exist*. 7. **In the Behaviors section, select Set Cache Policy** 8. **Select the storefront-catalog cache setting** 9. **Select Save** ### API To create the cache setting, send its body to the application's cache settings: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//cache_settings \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "storefront-catalog", "browser_cache": { "behavior": "override", "max_age": 0 }, "modules": { "cache": { "behavior": "override", "max_age": 600 } } }' ``` The API answers `201` with the new setting. Keep its `id` for the rule: ```json {"state":"executed","data":{"id":,"name":"storefront-catalog",...}} ``` To create the rule, send two criteria groups. Groups join with `and`, so a request matches only when its path is a catalog path and it carries no session cookie: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//request_rules \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "storefront - catalog cache", "active": true, "criteria": [ [ { "variable": "${uri}", "conditional": "if", "operator": "starts_with", "argument": "/products/" }, { "variable": "${uri}", "conditional": "or", "operator": "starts_with", "argument": "/category/" } ], [ { "variable": "${cookie_session_id}", "conditional": "if", "operator": "does_not_exist" } ] ], "behaviors": [{ "type": "set_cache_policy", "attributes": { "value": } }] }' ``` The API answers `202` with a `state` of `pending` and the rule as it was stored. Catalog and product pages requested without a session cookie are cached for 600 seconds, and browsers revalidate them on every visit. A new rule takes a few minutes to propagate. The [Build e-commerce storefronts](/en/documentation/use-cases/build-and-run-applications/build-e-commerce-storefronts/) use case uses the values of this example. --- ## Bypass the cache for several paths and a session cookie One rule can send every per-visitor request to the origin. The rule in this section matches the cart, checkout, and account paths, and any request that carries the session cookie, so a visitor with a session bypasses the cache on every path. It carries **Forward Cookies** as well, so the session cookie the origin sets reaches the visitor. Nothing this rule matches is cached, so the denylist cache setting of [Forward cookies from the origin to the user](#forward-cookies-from-the-origin-to-the-user) is not needed here. The example uses `/cart`, `/checkout`, `/account`, and `session_id`. Replace each one with your own. ### Console To create the bypass rule: 1. **Go to the Rules Engine tab** Access [Azion Console](https://console.azion.com/) > **Applications** > **your application**, then go to the **Rules Engine** tab. 2. **Select + Rule** 3. **Name the rule** Enter `storefront - bypass per-visitor pages`. 4. **Select Request Phase** 5. **Match the per-visitor paths** In the **Criteria** section, set the first criterion to `${uri}` *starts with* `/cart`. Add two criteria joined by **Or**: `${uri}` *starts with* `/checkout`, and `${uri}` *starts with* `/account`. 6. **Match the session cookie** Add a fourth criterion joined by **Or**: `${cookie_session_id}` *exists*. 7. **In the Behaviors section, select Bypass Cache** 8. **Add the Forward Cookies behavior** 9. **Select Save** ### API To create the bypass rule, send its four criteria in one group joined by `or`, and both behaviors: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/applications//request_rules \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "storefront - bypass per-visitor pages", "active": true, "criteria": [ [ { "variable": "${uri}", "conditional": "if", "operator": "starts_with", "argument": "/cart" }, { "variable": "${uri}", "conditional": "or", "operator": "starts_with", "argument": "/checkout" }, { "variable": "${uri}", "conditional": "or", "operator": "starts_with", "argument": "/account" }, { "variable": "${cookie_session_id}", "conditional": "or", "operator": "exists" } ] ], "behaviors": [{ "type": "bypass_cache" }, { "type": "forward_cookies" }] }' ``` The API answers `202` with a `state` of `pending` and the rule as it was stored. Cart, checkout, and account requests, and every request with a session, reach the origin, and Azion stores none of their responses. A new rule takes a few minutes to propagate. To confirm both rules, request a catalog page twice without a cookie, then the cart, then a catalog page with the session cookie, each with the `Pragma: azion-debug-cache` header: ```bash curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/products/blue-shirt curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/cart curl -sI -H "Pragma: azion-debug-cache" -H "Cookie: session_id=test" https://www.example.com/products/blue-shirt ``` The second catalog request carries `x-cache: HIT`. The cart and the request with the cookie carry `x-cache: BYPASS`. For how to read the header, refer to [Check the cache status of a response](/en/documentation/guides/application-performance/cache-and-purge/check-page-cache-time/). The [Build e-commerce storefronts](/en/documentation/use-cases/build-and-run-applications/build-e-commerce-storefronts/) use case uses the values of this example. These checks confirm the [Build e-commerce storefronts](/en/documentation/use-cases/build-and-run-applications/build-e-commerce-storefronts/) use case. --- ## Next steps - [Cache variation](/en/documentation/platform/applications/application-accelerator/cache-variation.md): What Bypass Cache does that a Max Age of 0 seconds does not. - [Cache Settings](/en/documentation/platform/applications/cache/cache-settings.md): Every field a cache setting carries, with its values and defaults. - [Verify cache indicators with ModHeader](/en/documentation/guides/application-performance/cache-and-purge/check-page-cache-time.md): Read the cache headers a request returns and confirm the policy you applied. - [Real-Time Purge](/en/documentation/platform/applications/cache/real-time-purge.md): Expire a cached object before its Max Age runs out. - [Build e-commerce storefronts](/en/documentation/use-cases/build-and-run-applications/build-e-commerce-storefronts.md): A storefront that caches catalog pages for visitors without a session and bypasses the cache for cart, checkout, and account. - [Accelerate websites and APIs with a CDN](/en/documentation/use-cases/improve-performance-and-reliability/accelerate-websites-and-apis-with-a-cdn.md): Two cache settings, one with Tiered Cache, and a rule that passes API calls through to the origin.