At Akamai, caching refers to objects retrieved from your origin server and stored at any number of edge servers. Edge servers can quickly deliver the cached objects to your API consumers.

Caching decreases the load on your origin server and reduces latency in serving objects to the end client. You can define caching properties for an entire API, HTTP error responses, content that you send downstream to clients, and individual API resources.

📘
You can also customize caching with the Property Manager behaviors. Note that the settings you customize in API Definitions override the Property Manager settings.

Access Caching

On the API Definitions page, in the Registered APIs section, select the API name you want to configure caching settings for.
Select the API version.
From the list of delivery options on the left, select Caching.

📘
Now you can customize the following caching options separately:

API caching

HTTP error responses caching

Downstream cacheability

Query parameters cache key

See the following sections to learn about the different ways in which you can configure caching for your API.

Customize API caching

API caching refers to the caching instructions that you set for your entire API. By default, the settings that you configure at this level apply to all resources associated with your API. If desired, API Gateway lets you further customize the downstream and resource-level caching settings.

📘
To learn more about caching at Akamai, read What you need to know about caching. Note that these topics focus more on websites than APIs, but the core explanations of caching behaviors apply to both environments.

Caching increases HTTP response speed, reduces the load on your origin server, and prevents the generation of duplicate responses. You can configure caching options at the API, downstream, and resource levels.

📘
You can also complete this task by using the API Endpoints API. Run the Edit cache settings operation. Learn more about Akamai's APIs.

Before you begin, ensure that you understand the implications of caching so that you refrain from caching sensitive information. For details about the caching options that Akamai offers, see the "Caching" section in the Edge Server Configuration Guide in Akamai Control Center.

📘
You can also configure the API caching settings in Property Manager using the Caching behavior. Note that the settings you customize in API Definitions override the Property Manager settings.

On the Caching settings page, enable Customize API caching. The caching settings that you configure in API Gateway control the caching of your registered API. If you enable it, any caching settings that you specified for the hostnames associated with your API in Property Manager do not apply.
From the API endpoint caching menu, select the type of caching that you want to implement.
For your API caching configuration, you can:
- serve the content from the origin and clear any versions from the cache (no store).
- serve the content from the origin but do not remove cached versions (bypass cache).
- cache the content.
- honor the caching headers from your origin.
To learn more about the options, see Caching options in Property Manager.

The caching settings that you configure at this level apply to all resources within your API. You can later change the caching settings for individual resources.
If you selected No store or Bypass cache, then skip the next step.
If you selected any other option:

a. In the Max age field, enter the maximum time for caching content. A setting of 0 means no-cache , which forces origin revalidation before serving the content. For the caching options that honor origin headers, this max age is only used when the origin does not specify one.

You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000.

b. Optional: To serve expired objects when revalidation with the origin server is not possible, set the Serve stale objects on origin error switch to Yes.

c. Optional: To set up an automatic refresh of your cached API content, enable Enable Cache Prefreshing.

Cache prefreshing

Cache prefreshing is the practice of refreshing your cached API content before its predefined time to live (TTL) expires. When you enable this feature, edge servers asynchronously refresh cached API content after a specified percentage of the content's TTL elapses. This way API consumers do not have to wait for a response from the origin and get their requested content faster.

You may find this feature useful if your API content changes frequently and you rely on manual cache purges to update it. Cache prefreshing expires your outdated content automatically and saves you time and effort in periods of high demand.

If a client sends a request to your API after the asynchronous refresh begins and before the TTL expires, edge servers continue to serve the older content to the client until its TTL expires, or until edge servers receive the refreshed content from the origin.

In API Definitions, on the Caching settings or GraphQL caching settings page, you may enter the percentage of content's TTL after which edge servers will asynchronously refresh the content in cache. You can define this percentage both at the API configuration and API resource levels.

See the Cache Prefreshing behavior in Property Manager.

Customize HTTP error responses caching

You can cache error responses sent from your origin to reduce the number of calls to origin when content is not available.

📘
You can also configure the API caching settings in Property Manager using the Cache HTTP Error Responses behavior. Note that the settings you customize in API Definitions override the Property Manager settings.

By default, edge servers cache error responses with codes 204, 305, 404, and 405 for 10 seconds. You can modify the caching times for these error responses and decide whether to serve stale responses when revalidation with your origin is not possible.

On the Caching settings page, enable the Customize HTTP error responses caching section.
A group of configuration parameters appears.
Select the type of caching that you want to implement.
If you select Cache, in the Max age field, enter the maximum time for caching HTTP error responses. You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000.
Optional: To preserve expired objects when revalidation with the origin server is not possible, enable the Preserve stale objects option.

Customize Downstream cacheability

Downstream caching refers to the caching instructions associated with objects sent with responses to clients, such as browsers, mobile devices, or client proxies.

📘
You can also configure the API caching settings in Property Manager using the Downstream Cacheability behavior. Note that the settings you customize in API Definitions override the Property Manager settings.

In the Downstream cacheability section, you can decouple caching in the last mile from the browser caching settings. When doing so, you can select whether to use the headers sent by your origin to control caching behavior or have the headers and their values controlled by edge servers.

By default, Akamai calculates the downstream caching lifetime based on your API-level caching instructions or your origin caching headers. If your API-level caching behavior is set to No store or Bypass cache, edge servers attempt to prohibit downstream caching by sending so-called cache-busting headers to clients. Cache-busting headers include Expires:<current_time>, Cache-Control: max-age=0, Cache-Control: no-store, and Pragma: no-cache.

To check the caching options you can implement, see the Downstream Cacheability behavior.

📘
To learn more about downstream caching, read Downstream caching. Note that this guide focuses more on websites than APIs, but the core explanations of caching behaviors apply to both environments.

Downstream caching refers to the caching instructions that calling API clients (for example, browsers) should follow.

On the Caching settings page, enable the Customize Downstream cacheability section.
Select the Caching option. See Downstream Cacheability to learn more about the options.
Select the Cache lifetime option. See Downstream Cacheability to learn more about the options.
If you selected Fixed value in the previous step, in the Max age field, enter the maximum time for caching content. You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000.
Select the Send headers option. See Downstream Cacheability to learn more about the options
Optional: To disallow storing of HTTP responses in a shared cache, set the Mark as private switch to Yes . This adds the Private directive to the Cache-Control header.

Customize query parameters cache key

A cache key is an index entry that uniquely identifies an object in a cache. You can customize cache keys by specifying whether to use a query string (or portions of it) in an incoming request to differentiate objects in a cache.

📘
You can also configure the API caching settings in Property Manager using the Cache Key Query Parameters behavior. Note that the settings you customize in API Definitions override the Property Manager settings.

By default, edge servers cache content based on the entire resource path and a query string. You can modify this default behavior by specifying that cache keys should not include a query string or a portion of it. This is especially useful for requests that include a query string that has no relation to the uniqueness of API content. For example, to track clients' interaction with an API, a unique session ID might be a part of a query string. This session ID might not affect the API content served to clients.

📘
The question mark symbol always precedes a query string. In the following path, session_id=12345 is a query string that represents a session ID: http://myhostname.akamai.com/userdata?session_id=12345.

You can customize cache keys by specifying whether to use a query string in an incoming request to differentiate objects in a cache.

On the Caching settings page, enable the Customize query parameters cache key section.
From the Behavior menu, select how you want to customize cache keys. See the Cache Key Query Parameters to learn more about the options.
If you selected Include only specified parameters or Exclude only specified parameters:
a. In the Parameters field, enter the parameters to be included in or excluded from cache keys.
b. Optional: Enable the Exact match switch. This setting pertains to how we parse query strings. See the Cache Key Query Parameters behavior to learn more about the options.

Resource level caching

You can set specific caching instructions for each resource in your API configuration.

By setting caching on a resource level, you tell API Gateway to ignore the global API-level caching settings when retrieving information about a resource and instead follow the caching instructions associated with the resource.

Configure resource caching

📘
You can configure resource caching only when you enable Customize API caching.

In the Resource level caching table of the Caching settings page, you can configure caching options for individual API resources. These individual resource settings take precedence over the general API caching configuration.

📘
You can only apply caching to resources associated with the GET method.

You can also control which individual resources inherit the top-level settings by selecting their Inherit check boxes.

On the Caching settings page, in the API endpoint caching field, select the type of caching that you want to apply to a resource.
In the Max age option, enter the maximum time for caching content. You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000.
Optional: If applicable, to serve expired objects when revalidation with the origin server is not possible, enable the Serve stale objects on origin error option.
Optional: Enable the Customize query parameters cache key option.
If applicable, from the Behavior menu, select how you want to customize cache keys.
Optional: To set up an automatic refresh of your cached API content, enable Enable Cache Prefreshing. In the Percentage of TTL field, enter the percentage of content's TTL at which the content should be refreshed. See Cache prefreshing to learn more.