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.

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

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.

You can implement one of the following caching options for your API:

• Cache. Enable caching of your API content in ​Akamai​ platform servers. This allows you to set the maximum time for keeping content in the edge server cache and specify whether to serve stale cached objects to clients when your origin is unavailable.

• No store. Disallow caching in ​Akamai​ platform servers and remove any existing cache entries from the edge server cache. This option turns off caching of your API content entirely.

• Bypass cache. Disallow caching in ​Akamai​ platform servers and keep the existing cache entries. You can choose this option if you expect your origin server to send alternate responses to clients. Consider the example of an origin server sending a 302 redirect in response to a failed authorization. By using the Bypass cache option, you prevent this alternate response from removing the requested object from edge server cache.

• Honor origin Cache-Control. Apply caching instructions as specified in your origin's Cache-Controlheader. Edge servers can honor the following settings from the Cache-Controlheader: max-age,no-store,no-cache(behaves like setting a zero second max-age), pre-check(serves as a max-agesetting if there is no max-age), post-check(serves as an edge prefresh settings).

• Honor origin Expires. Apply caching instructions as specified in your origin's Expiresheader. Based on the value in the Expiresheader, edge servers calculate an implied max age for keeping content in a cache. The implied max age is equal to the origin Expiresdate minus the origin current date. You can use this option if you expect the objects returned from your origin to change at a specific time.

• Honor origin Cache-Control and Expires. Apply caching instructions specified in your origin's Cache-ControlandExpiresheaders. In case of conflicts between the Cache-ControlandExpiresheaders, the Cache-Controlheader value takes precedence in determining the maximum age of keeping content in a cache.

📘

If you decide to honor origin headers, you must also set a Max age to use in case the relevant origin header is unreachable.

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.

Configure caching

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.

📘

API

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​.

1. On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API configuration you want to configure caching settings for.

2. From the menu, select Manage versions.

3. In the Version history panel, click the ellipsis icon (...) associated with the API configuration version you want to configure caching settings for.

4. From the list of delivery options, select Caching.

5. On the Caching settings page, set the Enable caching switch to Yes.
   The caching settings that you configure in API Gateway control the caching of your registered API. If this switch is set to Yes, any caching settings that you specified for the hostnames associated with your API in Property Manager do not apply.

6. In the API caching section, 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.

   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.

7. If you selected No store or Bypass cache, then skip the next step.

8. 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. To set up an automatic refresh of your cached API content, set the Enable cache prefreshing switch to Yes

   d. In the Percentage of max age field, enter the percentage of content's TTL at which the content should be refreshed.

9. Optional: Configure HTTP error caching. See Cache HTTP error responses.

10. Optional: Configure downstream caching. See Configure downstream caching.

11. Optional: Configure cache key query parameters. See Configure cache key query parameters.

12. Optional: Configure caching for individual resources. See Configure resource caching.

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.

If, for example, content has 10 minutes to live, and a response from the origin takes 30 seconds, the optimal setting would be 95% or lower of the content's TTL. This way, edge servers refresh the content in enough time to let API consumers receive that content without having to wait for the response from the origin, but not so early that it increases load on the origin.

Consider the following when setting the cache prefresh percentage:

• The frequency of API requests. Setting too high a percentage and having too few requests could mean the content expires and an API consumer must wait for the response from the origin. Setting it too low may result in unnecessarily high load on origin.

• The length of time for the origin to send the whole response. If the origin has not finished sending the new content by the time the original content expires, API consumers will have to wait for the origin to respond.

Configure caching HTTP error responses

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

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.

1. On the Caching settings page, in the Cache HTTP error responses section, set the Enable switch to Yes.
   A group of configuration parameters appears.

2. 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.

3. To preserve expired objects when revalidation with the origin server is not possible, set the Preserve stale objects switch to Yes.

Downstream caching

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

In the Downstream cacheability section, you can decouple caching in the last mile from the browser caching settings. When doing so, you can choose 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.

You can implement one of the following downstream caching options:

• Allow caching. Allow downstream caching, choose the caching lifetime policy and the headers that edge servers should send to clients. You can configure the cache lifetime policy in relation to the settings in your origin headers or edge servers' time-to-live (TTL), specify a fixed maximum age value, or calculate the lifetime based on the origin Cache-Controlheader. For more details on these options, see Cache lifetime options. You can also apply the Mark as private directive that prevents sensitive data from being stored in shared caches.

• Allow caching, require revalidation (no-cache). Allow downstream caching with a mandatory origin revalidation before a cached copy reaches the request sender. While the standard Allow caching option only revalidates with the origin once an object's TTL has expired, this option forces the browser to send an If-Modified-SinceGET request every time it requests an object. If the object has changed since the last time it was cached, the origin server sends the new version; otherwise, the origin sends an HTTP 304 Not Modifiedresponse. You can also apply the Mark as private directive that prevents sensitive data from being stored in shared caches.

• Don't allow caching (bust). Send cache-busting headers downstream to prohibit downstream caching.

• Pass cacheability headers from origin. Apply your origin's Cache-Controland/orExpiresheader settings to downstream clients. Your origin cache headers will be passed to clients without any alteration.

• Don't send headers, apply browser defaults. Don't send any caching headers and let client browsers cache content according to their default settings. The default settings may vary from browser to browser.

📘

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

Cache lifetime options

The following table lists the cache lifetime options that you can choose after selecting the Allow caching downstream caching option. The cache lifetime is determined based on the Expiresheader; each option listed below sets the Expiresheader to a specific value.

Configure downstream caching

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

1. Configure downstream caching:

Cache key query parameters

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.

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 in one of the following ways:

• Include all parameters (preserve order from request). Include in cache keys all query parameters from the request.

• Include all parameters (reorder alphabetically). Include in cache keys all query parameters from the request, but reorder them alphabetically.

• Exclude all parameters. Exclude from cache keys all query parameters in a request.

• Include only specified parameters. Include in cache keys only specific parameters that you define. You can either enforce an exact match of these parameters, or match the parameters that just begin with the strings you defined.

• Exclude only specified parameters. Exclude from cache keys only specific parameters that you define. You can either enforce an exact match of these parameters, or match the parameters that just begin with the strings you defined.

Configure cache key query parameters

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

1. In API definitions, go to the Registered APIs tab.

2. Click the action menu icon next to the API you want to modify, and select Manage versions.

3. Click the action menu icon, next to the version you want to edit, and select View/edit version.

4. From the menu on the left, select Caching.
   Caching settings page opens.

5. On the Caching settings page, in the Cache key query parameters section, set the Customize cache key switch to Yes.

6. From the Behavior menu, select how you want to customize cache keys.

7. 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. Set the Exact match switch to the desired value.

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

In the Resource level caching section 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.

If you decide to reset caching settings for all resources to the API level at any point, you can click Reset to API settings. You can also control which individual resources inherit the top-level settings by selecting their Inherit check boxes.

1. On the Caching settings page, in the Resource caching option column, select the type of caching that you want to apply to a resource.

2. In the Resource caching details column, 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.

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

4. Optional: Set the Customize cache key switch to Yes.

5. If applicable, from the Behavior menu, select how you want to customize cache keys.