Cache settings
Look up every field of a cache setting: browser and cache TTLs, stale cache, Tiered Cache, cache variation, the API body, errors, and limits.
A cache setting is a set of values that tell Cache how to store and serve a response. It belongs to one Application, and its values are the browser time to live (TTL), the cache TTL and behavior, stale cache, Large File Optimization, Tiered Cache, and the cache variations. A Rules Engine rule with the Set Cache Policy behavior applies the setting, and the setting acts only on the requests that this rule matches. To create one, refer to Create a cache setting.
Interfaces
Six interfaces create and change the same cache setting. The tables on this page name the Console control, the API field, and the CLI flag of each field.
| Interface | Create | Read, update, delete |
|---|---|---|
| Azion Console | The Cache Settings tab of an Application in Applications, then + Cache, which opens the Create Cache Settings drawer | The same tab lists every setting with its Name, Browser Cache, and Cache |
| Azion API v4 | POST /v4/workspace/applications/{application_id}/cache_settings |
GET, PUT, PATCH, and DELETE /v4/workspace/applications/{application_id}/cache_settings/{cache_setting_id}; GET /v4/workspace/applications/{application_id}/cache_settings lists them |
| Azion CLI | azion create cache-setting |
azion describe cache-setting, azion list cache-setting, azion update cache-setting, azion delete cache-setting |
azion.config.js |
An entry of the cache array of an Application, of type AzionCache |
The same entry |
| Azion Lib | createCacheSetting from azion/applications |
getCacheSetting, getCacheSettings, updateCacheSetting, and deleteCacheSetting from azion/applications |
| Terraform | The azion_application_cache_setting resource, whose page documents application_id and name |
The same resource |
PUT replaces the whole setting, and PATCH changes only the fields it sends. The list endpoint filters by id and name and pages with page and page_size. The API authenticates with a personal token in the Authorization: Token <token> header. For more information, refer to Personal tokens.
In azion.config.js, an AzionCache entry carries name, stale, queryStringSort, tieredCache, methods, browser.maxAgeSeconds, edge.maxAgeSeconds, cacheByCookie, and cacheByQueryString.
General
In Azion Console, the General section of the Create Cache Settings drawer holds the name. name is the only field the API requires.
| Console control | API field | Type | Values | Default | CLI flag |
|---|---|---|---|---|---|
| Name | name |
string | 1 to 250 characters, unique among the cache settings of the Application | required, no default | --name |
Browser Cache
The browser_cache object sets what the browser is told to keep. In Azion Console, its controls are in the Browser Cache section.
| Console control | API field | Type | Values | Default | CLI flag |
|---|---|---|---|---|---|
| Browser Cache radios | browser_cache.behavior |
enum | Honor cache policies (honor), Override cache settings (override), No cache (no-cache) |
honor |
--browser-cache-behavior |
| Max Age under Override cache settings | browser_cache.max_age |
integer, seconds | 0 to 31,536,000 | 0 |
--browser-cache-max-age |
honor keeps the Cache-Control and Expires headers the origin sends and forwards them to the browser. override replaces them with the TTL in browser_cache.max_age. For no-cache, the No cache option of Azion Console reads: “Disable browser caching to ensure content is always fetched directly from the server”. On azion update cache-setting, the flag for browser_cache.behavior is --browser-cache-settings.
Cache
The modules.cache object sets how long Azion keeps a copy of a response and what it does with that copy. In Azion Console, its controls are in the Cache section.
| Console control | API field | Type | Values | Default | CLI flag |
|---|---|---|---|---|---|
| Cache Behavior radios | modules.cache.behavior |
enum | Honor cache policies (honor), Override cache behavior (override) |
honor (API, CLI); Override cache behavior preselected in the Console |
--file only |
| Max Age | modules.cache.max_age |
integer, seconds | 0 to 31,536,000 | 60 (API, CLI, Console) |
--file only |
| Stale cache | modules.cache.stale_cache.enabled |
boolean | true, false |
false (API, CLI); on in the Console |
--file only |
| Large file optimization | modules.cache.large_file_cache.enabled |
boolean | true, false |
false (API, CLI); off in the Console |
--file only |
| Offset (KB) | modules.cache.large_file_cache.offset |
integer, kB | 1024, fixed |
1024 |
--file only |
| Tiered Cache | modules.cache.tiered_cache.enabled |
boolean | true, false |
false (API); off in the Console |
--tiered-caching-enabled alone fails with error 21001; use --file |
| Tiered Cache Region | modules.cache.tiered_cache.topology |
enum | Such as nearest-region or us-east-1 |
nearest-region (API); nearest-region, preselected in the Console |
--file only |
honor keeps the Cache-Control and Expires headers the origin sends, and override replaces them with the TTL in modules.cache.max_age. When the origin sends neither Cache-Control nor Expires, honor keeps the copy for the Max Age of the setting, modules.cache.max_age.
Stale cache, the stale_cache.enabled field, lets Azion serve an expired copy for a limited window when the origin fails to answer. Large File Optimization, the large_file_cache.enabled field, stores a large object in fragments, and large_file_cache.offset holds their size, fixed at 1,024 kB. Tiered Cache is a Feature of Cache that adds a second cache layer between the data center that answers a request and your origin. tiered_cache.enabled turns it on for the objects this setting caches, and tiered_cache.topology selects where that layer holds them. A tiered_cache object sent without enabled turns the layer on. For how each one behaves on a request, refer to Expiration and freshness.
Application Accelerator
The modules.application_accelerator object holds the cache variations of a setting. In Azion Console, its four Cache vary by controls are in the Application Accelerator section, which the Create Cache Settings drawer shows only while Application Accelerator is on in the Application. While Application Accelerator is off, the API refuses with error 21013 any variation in that object: a behavior other than ignore, or a method in cache_vary_by_method. An object that keeps those defaults is accepted, even with sort_enabled set to true.
Together, the fields of modules.application_accelerator configure Advanced Cache Key, a Feature of Application Accelerator. cache_vary_by_devices uses the device groups defined in Device Groups. For what each behavior does to the cache key, refer to Application Accelerator settings.
| Console control | API field | Type | Values | Default | CLI flag |
|---|---|---|---|---|---|
| Cache vary by Method > POST, OPTIONS | cache_vary_by_method |
array of enum, at most 2 values | post, options |
[] |
On create, --enable-caching-for-options and --file. On update, --enable-caching-for-options and --enable-caching-for-post |
| Cache vary by Query String > Behavior | cache_vary_by_querystring.behavior |
enum | Ignore (ignore), All (all), Allowlist (allowlist), Denylist (denylist) |
ignore |
--cache-by-query-string |
| Cache vary by Query String > Fields | cache_vary_by_querystring.fields |
array of string | query string argument names | [] |
--query-string-fields |
| Cache vary by Query String > Sort | cache_vary_by_querystring.sort_enabled |
boolean | true, false |
false |
On create, --file only. On update, --enable-caching-string-sort |
| Cache vary by Cookies > Behavior | cache_vary_by_cookies.behavior |
enum | Ignore (ignore), All (all), Allowlist (allowlist), Denylist (denylist) |
ignore |
--cache-by-cookies |
| Cache vary by Cookies > Fields | cache_vary_by_cookies.cookie_names |
array of string | cookie names | [] |
--cookie-names |
| Cache vary by Devices > Behavior | cache_vary_by_devices.behavior |
enum | Ignore (ignore), Allowlist (allowlist) |
ignore |
--file only |
| Cache vary by Devices > Device Group | cache_vary_by_devices.device_group |
array of integer | device group ids | [] |
--file only |
On azion create cache-setting, --enable-caching-for-options writes options whatever its value, and post takes --file. On azion update cache-setting, a call that passes one method flag drops the other method, so pass both flags to keep both.
ignore keeps the same key whatever the values are, and all varies the key by every value that arrives. allowlist varies it by the named values, and denylist varies it by every value except the named ones. fields, cookie_names, and device_group hold the named values. sort_enabled groups the same arguments under one key whatever order they arrive in. allowlist and denylist on the query string need at least one field, or the API returns error 21018. For the steps in Azion Console that set these controls, refer to Configure Advanced Cache Key for an application.
Request body and CLI command
The request body below creates a complete cache setting through POST /v4/workspace/applications/{application_id}/cache_settings:
The API answers with HTTP 201, state set to executed, and the new cache setting with its id under data:
The list endpoint wraps the cache settings of an Application in a page envelope:
The CLI writes the fields its flags cover from the command line:
The command prints the id of the new setting:
On azion create cache-setting, the flags cover browser cache, query-string and cookie variation, and OPTIONS caching, and azion update cache-setting also sets sort_enabled and POST caching. Every other field is set through --file with the JSON body: modules.cache.max_age, the cache behavior, stale cache, Large File Optimization, and Tiered Cache.
Errors
The API answers each request below with HTTP 400. The body carries the code, the title, and a detail, and a field error also points at the field.
| Code | Title | Cause | Detail | What to do |
|---|---|---|---|---|
21021 |
Edge Cache Max Age Lower Than The Minimum Allowed By Application's Application Accelerator Module |
modules.cache.max_age is below 60 on an Application without Application Accelerator. |
The value is lower than the minimum required when the Application's Application Accelerator Module is disabled., at /data/modules/cache/max_age, with meta.min_value set to 60 |
Set modules.cache.max_age to 60 or more, or turn on Application Accelerator on the Application. |
21020 |
Edge Cache Max Age Lower Than The Minimum Allowed By The Tiered Cache Module |
modules.cache.max_age is below 3, with tiered_cache.enabled set to true and Application Accelerator on. |
The value is lower than the minimum required by the Tiered Cache Module., at /data/modules/cache/max_age, with meta.min_value set to 3 |
Set modules.cache.max_age to 3 or more, or turn Tiered Cache off. |
21001 |
It's Not Possible To Use This Edge Cache Behavior. |
tiered_cache.enabled is true while modules.cache.behavior is honor. |
It's not possible to use this edge cache behavior while using Tiered Cache., at /data/modules/cache/behavior |
Set modules.cache.behavior to override; from the CLI, send the body with --file. |
21013 |
This Configuration Requires The Edge Application's Application Accelerator Module |
A modules.application_accelerator field varies the cache, with a behavior other than ignore or a method in cache_vary_by_method, on an Application without Application Accelerator. |
To use this value, you must first enable the Application Accelerator module in Edge Application's Main Settings., at the field, such as /data/modules/application_accelerator/cache_vary_by_method |
Set modules.application_accelerator.enabled to true on the Application, or remove the field. Main Settings shows where in Azion Console. |
21018 |
Query String Fields Are Required For Current Cache Vary By Query String Behavior |
cache_vary_by_querystring.behavior is allowlist or denylist, and fields is empty. |
The current behavior requires you to configure query string fields., at /data/modules/application_accelerator/cache_vary_by_querystring/fields |
List at least one field, or set the behavior to ignore or all. |
21014 |
Cannot Delete Cache Setting |
A DELETE targets a setting that a rule’s Set Cache Policy behavior still uses. |
This Cache Setting cannot be deleted because it is being used., at /data |
Change or delete that rule, then repeat the DELETE. |
10068 |
Max Value |
modules.cache.max_age or browser_cache.max_age is above 31,536,000, or large_file_cache.offset is above 1,024. |
Ensure this value is less than or equal to 31536000.; for the offset, Ensure this value is less than or equal to 1024. |
Lower the value to the ceiling the detail names. |
10046 |
Max Length |
name is longer than 250 characters. |
Ensure this field has no more than 250 characters. |
Shorten the name to 250 characters or fewer. |
10039 |
Invalid Choice |
tiered_cache.topology is not a topology the API accepts. |
"<value>" is not a valid choice., at /data/modules/cache/tiered_cache/topology |
Send a topology that the Azion API reference lists, such as nearest-region or us-east-1. |
10012 |
Unique Field |
name repeats the name of another cache setting of the same Application. |
This field must be unique., at /data/name |
Choose a name that no other cache setting of the Application uses. |
azion create cache-setting --tiered-caching-enabled true returns 21001, because the CLI sets the cache behavior only through --file, so the setting keeps the honor default.
Limits
The bounds below apply to one cache setting. Each row names the API’s answer past the value.
| Value | Bound | Past the bound |
|---|---|---|
name |
1 to 250 characters | HTTP 400, error 10046 |
modules.cache.max_age |
0 to 31,536,000 seconds | HTTP 400, error 10068 above the maximum |
modules.cache.max_age without Application Accelerator |
at least 60 seconds | HTTP 400, error 21021 |
modules.cache.max_age with Tiered Cache and Application Accelerator on |
at least 3 seconds | HTTP 400, error 21020 |
browser_cache.max_age |
0 to 31,536,000 seconds | HTTP 400, error 10068 |
large_file_cache.offset |
1,024 kB, fixed | HTTP 400, error 10068 above 1,024 |
cache_vary_by_method takes at most 2 values. The API accepts only 1,024 in large_file_cache.offset. To change the fragment size, contact the Sales team. For the size of a cached object and purge limits, refer to Applications limits.