# Cache settings

These `azion/applications` functions create, list, read, update, and delete the cache settings of an application. The application must have an origin first: on an application with none, the API refuses the cache setting with `HTTP error! Status: 400 - BAD REQUEST`.

---

## createCacheSetting

Creates a cache setting in an application. The application must have an origin first. On an application with none, the API refuses the cache setting, and the function returns `error` with the message `HTTP error! Status: 400 - BAD REQUEST`.

```typescript
function createCacheSetting(params: {
  applicationId: number;
  data: ApiBaseCacheSettingPayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionCacheSetting>>;
```

| Parameter       | Type                                                                                                               | Required | Description                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------ |
| `applicationId` | `number`                                                                                                           | Yes      | The ID of the application.                             |
| `data`          | [`ApiBaseCacheSettingPayload`](/en/documentation/devtools/azion-lib/application/types/#apibasecachesettingpayload) | Yes      | The settings of the cache setting. `name` is required. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions)                 | No       | Request options.                                       |

`browser_cache_settings` takes `honor`, `override`, or `ignore`, and `cdn_cache_settings` takes `honor` or `override`. With `override`, the sample also sets the matching maximum TTL field, `browser_cache_settings_maximum_ttl` or `cdn_cache_settings_maximum_ttl`.

Returns `data` as the created [AzionCacheSetting](/en/documentation/devtools/azion-lib/application/types/#azioncachesetting), with its `id`.

This sample is JavaScript, because TypeScript rejects string values for `browser_cache_settings` and `cdn_cache_settings`, whose types are enums the module does not export:

```javascript
import { createCacheSetting } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

// Create a new cache setting
const cacheSettingData = {
  name: 'my-cache-setting',
  browser_cache_settings: 'override',
  browser_cache_settings_maximum_ttl: 3600,
  cdn_cache_settings: 'override',
  cdn_cache_settings_maximum_ttl: 7200,
};

const { data: newCacheSetting, error } = await createCacheSetting({ applicationId, data: cacheSettingData });

if (error) {
  console.error('Error creating cache setting:', error);
} else {
  console.log('Cache setting created successfully:', newCacheSetting.id, newCacheSetting.name, newCacheSetting.cdn_cache_settings_maximum_ttl);
}
```

Output:

```text
Cache setting created successfully: 234567 my-cache-setting 7200
```

---

## getCacheSettings

Lists the cache settings of an application, one page at a time.

```typescript
function getCacheSettings(params: {
  applicationId: number;
  params?: ApiListCacheSettingsParams;
  options?: AzionClientOptions;
}): Promise<AzionApplicationCollectionResponse<AzionCacheSetting>>;
```

| Parameter       | Type                                                                                                    | Required | Description                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `applicationId` | `number`                                                                                                | Yes      | The ID of the application.                                                                                                                |
| `params`        | [`ApiListCacheSettingsParams`](/en/documentation/devtools/azion-lib/application/types/#list-parameters) | No       | Pagination: `page` and `page_size`. Leave out `sort` and `order`: the API refuses the values the type declares for them with a 400 error. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions)      | No       | Request options.                                                                                                                          |

Returns an [AzionApplicationCollectionResponse](/en/documentation/devtools/azion-lib/application/types/#azionapplicationcollectionresponse) whose `data.results` holds [AzionCacheSetting](/en/documentation/devtools/azion-lib/application/types/#azioncachesetting) objects.

```typescript
import { getCacheSettings } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

const { data: cacheSettings, error } = await getCacheSettings({
  applicationId,
  params: { page: 1, page_size: 20 },
});

if (error) {
  console.error('Error listing cache settings:', error);
} else {
  console.log(`Found ${cacheSettings?.count} cache settings:`, cacheSettings?.results.map((c) => `${c.id} ${c.name}`));
}
```

Output:

```text
Found 1 cache settings: [ '234568 my-other-cache-setting' ]
```

---

## getCacheSetting

Returns one cache setting of an application by its ID.

```typescript
function getCacheSetting(params: {
  applicationId: number;
  cacheSettingId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionCacheSetting>>;
```

| Parameter        | Type                                                                                               | Required | Description                  |
| ---------------- | -------------------------------------------------------------------------------------------------- | -------- | ---------------------------- |
| `applicationId`  | `number`                                                                                           | Yes      | The ID of the application.   |
| `cacheSettingId` | `number`                                                                                           | Yes      | The ID of the cache setting. |
| `options`        | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.             |

Returns `data` as an [AzionCacheSetting](/en/documentation/devtools/azion-lib/application/types/#azioncachesetting).

```typescript
import { getCacheSetting } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const cacheSettingId = 234567; // Replace with the actual cache setting ID

const { data: cacheSetting, error } = await getCacheSetting({ applicationId, cacheSettingId });

if (error) {
  console.error('Error retrieving cache setting:', error);
} else {
  console.log('Cache setting details:', cacheSetting?.id, cacheSetting?.name, cacheSetting?.browser_cache_settings, cacheSetting?.cdn_cache_settings);
}
```

Output:

```text
Cache setting details: 234567 my-cache-setting override override
```

---

## updateCacheSetting

Sends the cache setting fields you pass in a `PATCH` request.

```typescript
function updateCacheSetting(params: {
  applicationId: number;
  cacheSettingId: number;
  data: ApiUpdateCacheSettingPayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionCacheSetting>>;
```

| Parameter        | Type                                                                                                                 | Required | Description                                    |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------- |
| `applicationId`  | `number`                                                                                                             | Yes      | The ID of the application.                     |
| `cacheSettingId` | `number`                                                                                                             | Yes      | The ID of the cache setting to update.         |
| `data`           | [`ApiUpdateCacheSettingPayload`](/en/documentation/devtools/azion-lib/application/types/#apibasecachesettingpayload) | Yes      | The fields to change. Every field is optional. |
| `options`        | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions)                   | No       | Request options.                               |

Returns `data` as the updated [AzionCacheSetting](/en/documentation/devtools/azion-lib/application/types/#azioncachesetting). A payload without enum fields, such as `name` and a TTL, type-checks in TypeScript.

```typescript
import { updateCacheSetting } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const cacheSettingId = 234567; // Replace with the actual cache setting ID

const { data: updatedCacheSetting, error } = await updateCacheSetting({
  applicationId,
  cacheSettingId,
  data: { name: 'my-cache-setting-updated', cdn_cache_settings_maximum_ttl: 3600 },
});

if (error) {
  console.error('Error updating cache setting:', error);
} else {
  console.log('Cache setting updated:', updatedCacheSetting?.name, updatedCacheSetting?.cdn_cache_settings_maximum_ttl);
}
```

Output:

```text
Cache setting updated: my-cache-setting-updated 3600
```

---

## deleteCacheSetting

Deletes a cache setting of an application by its ID.

```typescript
function deleteCacheSetting(params: {
  applicationId: number;
  cacheSettingId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<void>>;
```

| Parameter        | Type                                                                                               | Required | Description                            |
| ---------------- | -------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- |
| `applicationId`  | `number`                                                                                           | Yes      | The ID of the application.             |
| `cacheSettingId` | `number`                                                                                           | Yes      | The ID of the cache setting to delete. |
| `options`        | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.                       |

A successful delete returns `error` with the message `Expected JSON response, but got: `, so the sample reads the cache setting back with [getCacheSetting](#getcachesetting). A `404` error confirms the delete.

```typescript
import { deleteCacheSetting, getCacheSetting } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const cacheSettingId = 234567; // Replace with the actual cache setting ID

const { error: deleteError } = await deleteCacheSetting({ applicationId, cacheSettingId });

// On success (HTTP 204) the envelope still carries an error, so confirm by reading it back
const { error } = await getCacheSetting({ applicationId, cacheSettingId });
if (error) {
  console.log(`Cache setting ${cacheSettingId} deleted (read back: ${error.message})`);
} else {
  console.error('Error deleting cache setting:', deleteError);
}
```

Output:

```text
Cache setting 234567 deleted (read back: HTTP error! Status: 404 - NOT FOUND)
```

---

## Related resources

- [Azion Lib](/en/documentation/devtools/azion-lib.md): The Azion Lib modules and the npm package each one ships in.
- [Applications](/en/documentation/devtools/azion-lib/application.md): The module's authentication, its response envelope, and the errors its functions report.
- [Application types](/en/documentation/devtools/azion-lib/application/types.md): The payload and response types these functions take and return.
- [Cache settings](/en/documentation/platform/applications/cache/cache-settings.md): The cache setting an application applies, with its TTLs and cache key.