# Application Accelerator quickstart

This guide instructs you through your first cache setting that varies the cache key. The example is a listing page whose response changes with one query string argument.

- Turn on [Application Accelerator](/en/documentation/platform/applications/#application-accelerator) on an application.
- Create a cache setting that holds the listing for 30 seconds and varies by the `category` argument.
- Add a Rules Engine rule that applies the cache setting to requests for `/products`.
- Request the listing twice, with two values of `category`, and read the cache key of each response.

Three objects produce that result, and each one depends on the one before it:

1. The **Application Accelerator** switch belongs to the application. It unlocks the fields that vary the cache key, and it removes the 60-second floor on the cache TTL.
2. The **cache setting** holds the cache behavior, the **Max Age**, and the variation. It names what the cache does, not which requests it does it to.
3. The [Rules Engine](/en/documentation/platform/applications/rules-engine/) rule applies the cache setting with the **Set Cache Policy** behavior. Its criteria decide which requests the cache setting covers.

Creating a cache setting changes no traffic. A cache setting that no rule applies never reaches a request.

`azion.config.js` and Azion Lib carry the same settings. For the field each interface sets, refer to [Application Accelerator settings](/en/documentation/platform/applications/application-accelerator/settings/).

---

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

## Prerequisites

- An Azion account. To create one, refer to [How to create an account on Azion](/en/documentation/fundamentals/creating-account/).
- The **Edit Applications** permission on the account. It grants permission to edit, create, and remove applications, and it also requires the permission **View Applications**. Refer to [Teams permissions](/en/documentation/fundamentals/teams-permissions/).
- An application that serves a path whose response changes with a query string argument. This guide uses the `/products` path and the `category` argument. To create an application, refer to [Applications quickstart](/en/documentation/platform/applications/quickstart/).

**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/) and `curl`.

---

## Turn on Application Accelerator

The module is off by default, and it belongs to one application at a time.

**Console**

To turn on the module in Azion Console:

1. **Open the Applications page**

   Access [Azion Console](https://console.azion.com/) > **Applications**.

2. **Select the application that serves the listing**

3. **Go to the Main Settings tab**

4. **Turn on the module**

   In the **Modules** section, turn on **Application Accelerator**.

5. **Select Save**

The application now accepts the cache fields the rest of this guide uses.

**CLI**

To turn on the module with the Azion CLI, replace `<application_id>` with [your application ID](/en/documentation/guides/application-development/getting-started/configure-main-settings/):

1. **Run the update command**

   ```bash
   azion update application --application-id <application_id> --application-accelerator true
   ```

2. **Read the output**

   The command confirms the application it updated:

   ```text
   Updated Application with ID <application_id>
   ```

The application now accepts the cache fields the rest of this guide uses.

**API**

To turn on the module with the Azion API, replace `[TOKEN VALUE]` with your personal token and `<application_id>` with [your application ID](/en/documentation/guides/application-development/getting-started/configure-main-settings/):

1. **Send the update request**

   ```bash
   curl --request PATCH \
     --url https://api.azion.com/v4/workspace/applications/<application_id> \
     --header 'Accept: application/json' \
     --header 'Authorization: Token [TOKEN VALUE]' \
     --header 'Content-Type: application/json' \
     --data '{
     "modules": {
       "application_accelerator": {
         "enabled": true
       }
     }
   }'
   ```

2. **Read the response**

   A `202` carries `"state": "pending"`, and the response echoes every module of the application:

   ```json
   {
     "cache": { "enabled": true },
     "functions": { "enabled": true },
     "application_accelerator": { "enabled": true },
     "image_processor": { "enabled": false }
   }
   ```

   The values of the other modules are the ones the application already held. Only `application_accelerator` changed.

The application now accepts the cache fields the rest of this guide uses.

> **Caution**
>
> Turning on a module can generate usage-related costs. For more information, refer to [Pricing](/en/documentation/fundamentals/pricing/#application-accelerator).

---

## Create a cache setting that varies by query string

A cache setting is where the cache behavior and the variation live. The **Max Age** of `30` seconds below is the point of the exercise: without Application Accelerator, the shortest cache TTL an application accepts is 60 seconds.

**Console**

To create the cache setting in Azion Console:

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

2. **Select + Cache**

3. **Name the cache setting**

   Enter a value in **Name**. For example: `product-listing`.

4. **Set the cache behavior and the TTL**

   Under **Cache**, select *Override cache behavior* and set **Max Age** to `30`.

5. **Vary the cache key by the query string**

   Under **Application Accelerator**, open **Cache vary by Query String** and set **Behavior** to *Allowlist*.

6. **Name the argument that varies the key**

   Add `category` to the field list under **Behavior**.

7. **Sort the query string arguments**

   Turn on **Sort**.

8. **Select Save**

The cache setting appears in the **Cache Settings** tab. It holds an object for 30 seconds and gives each value of `category` its own cached object.

**CLI**

To create the cache setting with the Azion CLI, send the body from a file: the command flags do not reach **Max Age**.

1. **Write the cache setting to a file**

   Save the following as `cache-setting.json`:

   ```json
   {
     "name": "product-listing",
     "browser_cache": { "behavior": "honor" },
     "modules": {
       "cache": {
         "behavior": "override",
         "max_age": 30
       },
       "application_accelerator": {
         "cache_vary_by_querystring": {
           "behavior": "allowlist",
           "fields": ["category"],
           "sort_enabled": true
         }
       }
     }
   }
   ```

2. **Create the cache setting**

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

   The command prints the id of the new cache setting:

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

3. **Read the cache setting back**

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

   This excerpt of the output carries the fields the file set:

   ```json
   {
     "id": 123462,
     "name": "product-listing",
     "modules": {
       "cache": {
         "max_age": 30
       },
       "application_accelerator": {
         "cache_vary_by_querystring": {
           "behavior": "allowlist",
           "fields": ["category"],
           "sort_enabled": true
         }
       }
     }
   }
   ```

The cache setting holds an object for 30 seconds and gives each value of `category` its own cached object. Record the id: the rule in the next stage selects the cache setting by it. 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 your application ID:

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": "product-listing",
     "browser_cache": { "behavior": "honor" },
     "modules": {
       "cache": {
         "behavior": "override",
         "max_age": 30
       },
       "application_accelerator": {
         "cache_vary_by_querystring": {
           "behavior": "allowlist",
           "fields": ["category"],
           "sort_enabled": true
         }
       }
     }
   }'
   ```

2. **Read the response**

   A `201` carries `"state": "executed"` and the cache setting. This excerpt carries the `id` and the fields the request set:

   ```json
   {
     "state": "executed",
     "data": {
       "id": 123461,
       "name": "product-listing",
       "modules": {
         "cache": {
           "behavior": "override",
           "max_age": 30
         },
         "application_accelerator": {
           "cache_vary_by_querystring": {
             "behavior": "allowlist",
             "fields": ["category"],
             "sort_enabled": true
           }
         }
       }
     }
   }
   ```

   A `max_age` below 60 is accepted only while Application Accelerator is on.

The cache setting holds an object for 30 seconds and gives each value of `category` its own cached object. Record the `id`: the rule in the next stage selects the cache setting by it.

---

## Apply the cache setting with a rule

A cache setting reaches a request only when a rule applies it.

**Console**

To apply the cache setting to the listing path in Azion Console:

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

2. **Select + Rule**

3. **Name the rule**

   Enter a name for the rule. For example: `Cache the product listing`.

4. **Set the phase**

   Select **Request Phase**.

5. **Select the variable**

   In the **Criteria** section, select the `${uri}` variable.

6. **Select the comparison operator**

   Select *starts with* as the comparison operator.

7. **Enter the argument**

   Enter `/products` as the argument.

8. **Select the behavior**

   In the **Behaviors** section, select **Set Cache Policy**.

9. **Select the cache setting you created**

10. **Select Save**

The rule applies the cache setting to every request whose URI starts with `/products`.

**CLI**

To add the rule with the Azion CLI, send the body from a file: the criteria carry `${uri}`, which a shell expands.

1. **Write the rule to a file**

   Save the following as `rule.json`, with the id of your cache setting in `attributes.value`:

   ```json
   {
     "name": "Cache the product listing",
     "active": true,
     "criteria": [
       [
         {
           "conditional": "if",
           "variable": "${uri}",
           "operator": "starts_with",
           "argument": "/products"
         }
       ]
     ],
     "behaviors": [
       {
         "type": "set_cache_policy",
         "attributes": { "value": 123462 }
       }
     ]
   }
   ```

2. **Create the rule**

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

   The command prints the id of the new rule:

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

The rule applies the cache setting to every request whose URI starts with `/products`.

**API**

To add the rule with the Azion API, send the body from a file: the criteria carry `${uri}`, which a shell expands.

1. **Write the rule to a file**

   Save the following as `rule.json`, with the `id` the cache setting create returned in `attributes.value`:

   ```json
   {
     "name": "Cache the product listing",
     "active": true,
     "criteria": [
       [
         {
           "conditional": "if",
           "variable": "${uri}",
           "operator": "starts_with",
           "argument": "/products"
         }
       ]
     ],
     "behaviors": [
       {
         "type": "set_cache_policy",
         "attributes": { "value": 123461 }
       }
     ]
   }
   ```

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 `"state": "pending"` and the rule, with its `id`, its `name`, whether it is `active`, the behaviors it holds, and the `order` it holds among the rules of the application.

The rule applies the cache setting to every request whose URI starts with `/products`.

A new rule takes a few minutes to propagate. Wait before you request the path.

---

## Read the cache key

Azion returns the cache key of an object when the request carries the Azion debug header `Pragma: azion-debug-cache`. Reading that key for two values of `category` shows the variation the cache setting created.

Your application answers on a domain in the format `xxxxxxxxx.map.azionedge.net`. To set the domain for your application, refer to [Add a custom domain to a workload](/en/documentation/guides/platform/migration/configure-a-domain/).

Replace `<your-azion-domain>` with that domain, and request the listing with one value:

```bash
curl -I -H "Pragma: azion-debug-cache" "https://<your-azion-domain>/products?category=shoes"
```

The response carries two Azion debug headers. This excerpt is from an application served at `www.example.com`, and HTTP/2 sends header names in lowercase:

```text
x-cache: MISS from 203.0.113.10 with HTTP/2.0
x-cache-key: httpswww.example.com/products?category=shoes
```

`x-cache` carries the cache status, the address of the data center that answered, and the protocol of the request. `x-cache-key` carries the cache key, which concatenates the scheme, the host, the path, and the query string arguments the allowlist named.

Request the same path with a different value:

```bash
curl -I -H "Pragma: azion-debug-cache" "https://<your-azion-domain>/products?category=hats"
```

The argument changed, so the key changed with it:

```text
x-cache-key: httpswww.example.com/products?category=hats
```

Two keys are two cached objects, which is what the allowlist asked for. For the full format of a cache key, refer to [Cache key format](/en/documentation/platform/applications/cache/cache-keys/#key-format).

Your application now caches the `/products` listing for 30 seconds and keeps one object per value of `category`.

---

## Next steps

- [Cache variation](/en/documentation/platform/applications/application-accelerator/cache-variation.md): What each distinct value of a varying attribute costs, and how a cache TTL of zero differs from Bypass Cache.
- [Application Accelerator settings](/en/documentation/platform/applications/application-accelerator/settings.md): The name, type, and default of every field this guide set, per interface.
- [Limits](/en/documentation/platform/applications/limits.md#application-accelerator): The values that bound a cache setting, including the TTL floor and ceiling.
- [Configure Advanced Cache Key](/en/documentation/guides/application-performance/cache-and-purge/advanced-cache-key.md): Vary the cache key by cookie and by device group, beyond the query string.
- [Real-Time Purge](/en/documentation/platform/applications/cache/real-time-purge.md): Remove an object that varies, which a URL purge alone does not reach.
- [Verify cache indicators](/en/documentation/guides/application-performance/cache-and-purge/check-page-cache-time.md): Read the same Azion debug headers in a browser instead of a terminal.