# Cache quickstart

This guide instructs you through caching a path of your application for the first time. By the end you will have:

- A cache setting that keeps a copy of each response for 300 seconds.
- A [Rules Engine](/en/documentation/platform/applications/rules-engine/) rule that applies the setting to one path prefix.
- The cache status of a response, read from its `x-cache` header.

The result rests on four objects, in this order. The **application** carries the [Cache](/en/documentation/platform/applications/#cache) module, which is on for every application. The **cache setting** belongs to the application and holds the TTL, the time Azion keeps a copy. The **rule**, also on the application, matches requests by path and applies the setting through the **Set Cache Policy** behavior. A matching **request** is answered from the stored copy when one exists, and its response carries `x-cache` with `HIT`. Until a rule names it, a cache setting does nothing.

---

Select the interface you will use. The prerequisites and every stage below follow that choice.

## Prerequisites

- An application that already serves content on a domain. To create one, refer to [Applications quickstart](/en/documentation/platform/applications/quickstart/).
- The URL of a static object the application serves, such as an image, to check at the end.
- `curl` on your machine, for the cache status check at the end.

**Console**

- Access to Azion Console. To sign in, refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/).

**CLI**

- The [Azion CLI](/en/documentation/devtools/cli/) installed and authorized.

**API**

- A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/).

---

## Create a cache setting

A cache setting holds how long Azion keeps a copy of a response. This one keeps each copy for 300 seconds.

**Console**

To create the cache setting in Azion Console:

1. **Open the application**

   Access [Azion Console](https://console.azion.com/) > **Applications**, then select the application that serves your content.

2. **Go to the Cache Settings tab**

3. **Select + Cache**

4. **Name the cache setting**

   In **Name**, enter `static-assets`.

5. **Keep Override cache behavior selected**

   Under **Cache**, keep *Override cache behavior* selected. With this option, **Max Age** replaces the TTL the origin sends.

6. **Set Max Age**

   In **Max Age**, replace `60` with `300`.

7. **Select Save**

The new setting appears in the **Cache Settings** list, which shows its **Name**, **ID**, **Browser Cache**, and **Cache**.

**CLI**

To create the cache setting with the Azion CLI, replace `<application_id>` with the ID of your application:

1. **Save the request body**

   The command reads the setting from a JSON file. Save this body as `cache-setting.json`:

   ```json
   {
     "name": "static-assets",
     "browser_cache": { "behavior": "honor" },
     "modules": {
       "cache": {
         "behavior": "override",
         "max_age": 300
       }
     }
   }
   ```

2. **Run the create command**

   ```bash
   azion create cache-setting --application-id <application_id> --file cache-setting.json
   ```

   The command confirms the setting and returns its ID:

   ```text
   Created Cache Settings configuration with ID 123460
   ```

3. **Read the setting back**

   Replace `123460` with the ID the create command returned:

   ```bash
   azion describe cache-setting --application-id <application_id> --cache-setting-id 123460 --format json
   ```

   The output reports `modules.cache.max_age` as `300`.

The cache setting exists on the application. Record its ID: the rule in the next stage names it.

> **Note**
>
> The command flags do not set **Max Age**, the cache behavior, stale cache, Large File Optimization, or Tiered Cache. Pass the request body with `--file` for those fields. For every flag the command accepts, refer to [Azion CLI create](/en/documentation/devtools/cli/resources/).

**API**

To create the cache setting with the Azion API, replace `[TOKEN VALUE]` with your personal token and `<application_id>` with the ID of your application:

1. **Send the create request**

   ```bash
   curl --request POST \
     --url https://api.azion.com/v4/workspace/applications/<application_id>/cache_settings \
     --header 'Accept: application/json' \
     --header 'Authorization: Token [TOKEN VALUE]' \
     --header 'Content-Type: application/json' \
     --data '{
     "name": "static-assets",
     "browser_cache": { "behavior": "honor" },
     "modules": {
       "cache": {
         "behavior": "override",
         "max_age": 300
       }
     }
   }'
   ```

2. **Read the response**

   A `201` carries the setting, with every field the request left out filled by its default:

   ```json
   {
     "state": "executed",
     "data": {
       "id": 123459,
       "name": "static-assets",
       "browser_cache": { "behavior": "honor", "max_age": 0 },
       "modules": {
         "cache": {
           "behavior": "override",
           "max_age": 300,
           "stale_cache": { "enabled": false },
           "large_file_cache": { "enabled": false, "offset": 1024 },
           "tiered_cache": { "enabled": false }
         }
       }
     }
   }
   ```

The cache setting exists on the application. Record the `id`: the rule in the next stage names it.

> **Note**
>
> A **Max Age** below 60 seconds requires the [Application Accelerator](/en/documentation/platform/applications/#application-accelerator) module on the application.

---

## Apply the setting with a rule

A cache setting does nothing until a rule names it. This rule applies `static-assets` to every request whose path matches a prefix you choose.

**Console**

To create the rule in Azion Console:

1. **Go to the Rules Engine tab**

2. **Select + Rule**

3. **Name the rule**

   Enter a name such as `cache-static-assets`.

4. **Select Request Phase**

5. **Set the criteria**

   Under **Criteria**, select `${uri}` and an operator. As the argument, enter the path prefix to cache, such as `/static/`.

6. **Add the Set Cache Policy behavior**

   Under **Behaviors**, select **Set Cache Policy**, then select `static-assets`.

7. **Select Save**

The rule appears in the list and applies `static-assets` to every request whose path matches its criteria.

**CLI**

To create the rule with the Azion CLI, replace `<application_id>` with the ID of your application:

1. **Save the request body**

   The criteria carry `${uri}`, which a shell expands, so the rule goes in a file. Save this body as `rule.json`, and replace `123460` with the ID of the cache setting from the previous stage:

   ```json
   {
     "name": "cache-static-assets",
     "active": true,
     "criteria": [
       [
         {
           "conditional": "if",
           "variable": "${uri}",
           "operator": "starts_with",
           "argument": "/static/"
         }
       ]
     ],
     "behaviors": [
       {
         "type": "set_cache_policy",
         "attributes": { "value": 123460 }
       }
     ]
   }
   ```

2. **Run the create command**

   ```bash
   azion create rules-engine --application-id <application_id> --phase request --file rule.json
   ```

   The command confirms the rule and returns its ID:

   ```text
   Created Rules Engine with ID 234570
   ```

The rule exists on the application and applies `static-assets` to every request whose path starts with `/static/`.

**API**

To create the rule with the Azion API, replace `[TOKEN VALUE]` with your personal token and `<application_id>` with the ID of your application:

1. **Save the request body**

   The criteria carry `${uri}`, which a shell expands, so the body goes in a file instead of on the command line. Save this body as `rule.json`, and replace `123459` with the ID of the cache setting from the previous stage:

   ```json
   {
     "name": "cache-static-assets",
     "active": true,
     "criteria": [
       [
         {
           "conditional": "if",
           "variable": "${uri}",
           "operator": "starts_with",
           "argument": "/static/"
         }
       ]
     ],
     "behaviors": [
       {
         "type": "set_cache_policy",
         "attributes": { "value": 123459 }
       }
     ]
   }
   ```

2. **Send the create request**

   ```bash
   curl --request POST \
     --url https://api.azion.com/v4/workspace/applications/<application_id>/request_rules \
     --header 'Accept: application/json' \
     --header 'Authorization: Token [TOKEN VALUE]' \
     --header 'Content-Type: application/json' \
     --data @rule.json
   ```

3. **Read the response**

   A `202` carries the rule, and the state `pending` means the platform is still applying it:

   ```json
   {
     "state": "pending",
     "data": {
       "id": 234569,
       "name": "cache-static-assets",
       "active": true,
       "behaviors": [
         {
           "type": "set_cache_policy",
           "attributes": { "value": 123459 }
         }
       ],
       "order": 2
     }
   }
   ```

The rule exists on the application and applies `static-assets` to every request whose path starts with `/static/`.

> **Note**
>
> A new rule can take a few minutes to propagate. Wait before you check the cache status.

---

## Check the cache status

The request header `Pragma: azion-debug-cache` makes the response carry two debug headers. `x-cache` holds the cache status, the IP of the server that answered, and the protocol. `x-cache-key` holds the key that indexes the copy.

1. **Request the object with the debug header**

   Request an object under the path the rule matches, with your own host and path:

   ```bash
   curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/static/site.js
   ```

2. **Read the cache status**

   The response carries the two debug headers. Under HTTP/2, the header names arrive in lowercase:

   ```http
   x-cache: MISS from 192.0.2.10 with HTTP/2.0
   x-cache-key: httpswww.example.com/static/site.js
   ```

   `MISS` means the object was not in the cache: Azion fetched it from the origin and may store the response.

3. **Run the same command again**

4. **Read the cache status again**

   A response answered from the stored copy carries `HIT`. `x-cache` also names the server that answered.

Your application now keeps a copy of each matching response for 300 seconds. `x-cache` tells you when a response came from that copy. A response can also carry another status, such as `REVALIDATED`. For every status value, refer to [Cache keys](/en/documentation/platform/applications/cache/cache-keys/).

---

## Next steps

- [Expiration and freshness](/en/documentation/platform/applications/cache/expiration-and-freshness.md): How a request finds a stored copy, how the TTL expires it, and what stale cache does when the origin fails.
- [Cache settings](/en/documentation/platform/applications/cache/cache-settings.md): Every field a cache setting carries, including the browser TTL and stale cache.
- [Create a cache setting](/en/documentation/guides/application-performance/cache-and-purge/tune-cache-settings.md): The same cache setting and rule through the Azion API and the Azion CLI.
- [Purge cached content](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content.md): Remove a stored copy before its TTL expires, by URL, cache key, or wildcard.
- [Applications limits](/en/documentation/platform/applications/limits.md#cache): The bounds on TTL values, cache setting names, object size, and purge requests.
- [Troubleshoot Applications](/en/documentation/platform/applications/troubleshooting.md#cache): What to check when a response is not served from the cache.