Configure the Offload origin rule

Use this rule to control caching content at the edge and in an end user's browser. As a result, fewer requests go to your origin, fewer bytes leave your data centers, and your assets are closer to your users.

Check out the origin server workflows

All of the sub-rules and behaviors here apply to your origin server and look to improve its performance in the flow of a request. So, before you can begin configuring these, you need to set up your origin server. If you haven't yet, take a look at Set up an origin server for Ion to see examples of common workflows you can follow to set one up.


Set up behaviors in the parent rule

The Offload origin rule is comprised of several content-caching-related behaviors. Its Criteria is default set to all requests to help optimize delivery via the caching-related settings you set here.

Caching

Recommended Setting: Any that enables caching

Caching your content on edge servers makes it closer to requesting end users to help speed its delivery. It also reduces the load on your origin server by decreasing the number of hits from end users for your content. This is what ​Akamai​ refers to as "origin offload." Use the drop-down here to determine if and how you want your content cached on the ​Akamai​ edge servers for delivery to your end users.

👍

To help with origin offload, we recommend that you enable some form of caching and cache as much as you can. Review all of the other behaviors in this rule and ensure that you're caching everything for your site or app that can be cached. However, before you apply any caching, we recommend that you review What you need to know about caching.

  • Cache. Select this option to cache content in ​ edge servers for a time to live (TTL) you specify in the Maxage field.

  • No store. Select this option to serve the content from the origin and clear any versions from the edge cache.

  • Bypass cache. Select this option to serve the content from your origin without removing any cached versions from edge servers.

  • Honor origin Cache-Control and Expires. Select this option to configure content caching by honoring both the Cache-Control and Expires response headers from your origin.

  • Honor origin Cache-Control. Select this option to configure content caching by honoring the Cache-Control response header from your origin.

  • Honor origin Expires. Select this option to configure content caching by honoring the Expires response header from your origin.

📘

No store and Bypass cache are not supported if you're using ​Akamai​ NetStorage as your origin server. You need to apply some form of caching.

Use caching and Fast Purge

When it comes to real-time content, you might see caching as the enemy. But typically, real-time simply means instant updates to reflect data changes. To achieve this real-time aspect, you may think you have to skip caching and have requests go directly to your origin. But, you can use caching to increase origin offload and add ​Akamai​ Fast Purge to help. For example:

  1. Set Caching to Cache with a long Maxage to serve as a TTL. All of your relevant content will be cached to edge servers, geographically close to your end users, allowing for quicker access.
  1. Set up Fast Purge to purge content in under 5 seconds when it updates. As your website or app content is updated, its cached equivalent is purged from edge servers and replaced by new, updated content.

  2. Disable (or minimize) the downstream cache hold. Your end users will continuously fetch updates from edge servers, rather than your origin. This way, the latest version will be available when updates are made.

How to use Fast Purge

You can set up cache purges in response to content updates at your origin, so that the cache is intelligently purged every time specific content is changed. You can do this using the ​Akamai​ CLI for Purge. You can also manually purge content using the Fast Purge tool in ​Akamai Control Center​. Check out some basics on purging for more information.

Set up caching for specific object types

This rule applies generic caching for all of your website or app assets. You can override this generic caching setting for specific file types in your Ion property. In fact, we've already done it for you for several common website and app-related file types, using sub-rules in your property:

Tiered Distribution

Recommended Setting: On (You need some form of Caching applied, too.)

Tiered Distribution helps maximize the delivery of cacheable content from ​Akamai​ edge servers, to reduce traffic on your origin server. ​Akamai​ servers located close to your origin server are designated as parents, that cache your content and serve it to other servers on our platform. This reduces the number of end-user requests that require responses from your origin. If you're caching content, we recommend that you enable it and select the type of map:

  • Global. Select this if your goal is to reduce latency in your end users' requests.

  • Local. Select the appropriate geographic region if your primary goal is to maximize the offload of your origin server in that region.

Additional considerations

Before you apply Tiered Distribution, consider these points:

  • Tiered Distribution is intended for cached objects. If you've set Caching to No store or Bypass cache, disable Tiered Distribution. If you leave it enabled, a request is routed through a longer, Tiered Distribution-specific server path and then to your origin. This creates longer response times for your end users. You can use SureRoute in the Accelerate Delivery, instead. It's similar to Tiered Distribution, but it's used to accelerate non-cacheable content. If you're avoiding caching because you're concerned about real-time content, consider using Fast Purge.

  • You need to include the Allow All Methods on Parent Servers behavior. This is included by default, as a sub-rule in the Strengthen security rule in your Ion property. Make sure it remains set to On, if you enable Tiered Distribution.

  • Tiered Distribution creates midgress traffic. Tiered distribution uses a separate network of cache hierarchy parent servers on the ​Akamai​ edge, that are geographically positioned to help deliver content even quicker. So, regular edge servers need to communicate with these servers during a request. This is what's called midgress traffic. If you add Tiered Distribution, traffic data is separated into regular edge traffic and midgress traffic. Keep this in mind when reviewing reporting data.

Validate Entity Tag (ETag)

Recommend setting: Optional (Only applicable if you're using Etags.)

An Etag is an HTTP header used to validate a cached object. Typically, the Etag header contains an identifier that represents a specific version of an object. When enabled, edge servers compare the request’s ETag header with the header of the cached object. If these don't match, the edge server gets a new copy of the object from your origin and sends it to the client. This validation occurs in addition to the default validation of Last-Modified and If-Modified-Since headers.

If you enable this, requests from your end-user clients need to include the appropriate Etag header to ensure the proper object is fetched.

Remove Vary Header

Recommended Setting: On (This removes the vary header.)

Some web servers add Vary HTTP headers to content by default. This header lets applications vary content based on the browser in use, or other client properties. Unfortunately, this makes it difficult to cache content. If you've followed the recommended process and set up some form of Caching, you should set this to On. Ion will automatically remove the Vary HTTP header to allow for caching.

Include the Vary HTTP header

If you need to disable this for specific use cases, we recommend that you add this behavior to a separate rule and set specific match criteria. For example, you could set up a unique property hostname for these requests, using a different domain. Set up the rule to match requests to this specific property hostname, and the Vary HTTP header will be maintained.

Additionally, you can disable this and Ion can still cache the associated object if the Vary HTTP header contains only Accept-Encoding and Gzip is present in the Content-Encoding header.

Cache HTTP Error Responses

Recommended setting: On

Keep this behavior with Enable set to On to cache error responses on your origin, and reduce the number of requests to it. This applies to responses that return HTTP status codes 204, 305, 400, 404, 405, 500, 501, 502, 503, 504, or 505.

  • Max-age. Determine how long these error responses should continue to be cached after the first error response is recognized.

  • Preserve Stale Objects. We recommend that you set this to On. Edge servers will keep and serve stale cached objects when serving responses with status codes 400, 500, 502, 503, or 504. End-users will still be able to access content during errors without re-fetching and re-caching content from your origin.

Also, see this behavior's information regarding cache poisoning attacks.

Cache Key Query Parameters

Recommended setting: Optional

Use this behavior to determine how query strings should be handled with requests for cached content. It's default set to Include all parameters (preserve order form request) so that all query string parameters in a request are included, and they're applied in the order they exist in the request.

📘

There are some additional considerations

  • If Resource Optimizer via Adaptive Acceleration is also being applied to the same requests, you can't manipulate cache key query parameters. You'll need to make sure the behavior is set to either Exclude all parameters or Include all parameters (preserve order from the request).
  • If you're using NetStorage as your origin, cache key query parameters aren't supported. This needs to be set to Exclude all parameters.

Cache Prefreshing

Recommended setting: On with Percentage of TTL at 90%

If you've enabled some form of Caching, you can enable this to refresh cached content before the "maxage" you've set for it expires. This way, end users won't have to wait for a response from your origin server when the maxage expires and content needs to be re-cached to the edge. Cache Prefreshing can be helpful if your content changes frequently, and you use manual cache purges to update it. It expires your outdated content automatically and saves you time and effort during high demand.

If an end user sends a request after a refresh begins and before the maxage expires, edge servers keep serving the older content to the end user until its maxage expires, or until edge servers receive the refreshed content from the origin, whichever happens first.

Using the recommended (default) settings, assume your cached content has a maxage set to 5 minutes, and a response from your origin takes 30 seconds. The Percentage of TTL is 90%, so ​Akamai​ begins to refresh your content at the 4-minute, 30-second point. This is enough time that end users will receive it without having to wait for the response from the origin, but not so early that it will increase the load on your origin server.

The percentage you choose has some dependencies:

  • The frequency of end-user requests. Setting too high a percentage and having too few requests could mean the content expires, and an end user has to wait for the response from the origin. Setting it too low may result in an unnecessarily high load on your origin.

  • The length of time it takes your origin to send the whole response. If the origin hasn't finished sending the new content by the time the original content expires, end users will have to wait for the origin to respond.

Downstream Cacheability

Recommended setting: Optional (Settings are contingent on what's set for Caching.)

Downstream caching refers to the caching instructions that an end user's client, such as a browser or mobile app should follow. You can use this behavior to override default client caching settings during the "last mile" of the request when edge servers are delivering your content to an end user. You can choose to have the caching headers controlled by edge servers or use the headers sent by your origin.

By default, ​​Akamai​ calculates the downstream caching lifetime based on what you've set for Caching, or what's in your origin caching header. If your Caching behavior is set to No store or Bypass cache, edge servers try to stop downstream caching by sending what we refer to as "cache-busting" headers to the browser or app. Cache-busting headers include Expires:<current_time>, Cache-Control: max-age=0, Cache-Control: no-store, and Pragma: no-cache.

You can add one of these downstream caching options:

  • Allow caching (Default). This allows downstream caching and lets you 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 what you've set as the maxage for Caching, specify a fixed maximum age value, or calculate the lifetime based on the origin Cache-Control header. For more details on these options, see Cache lifetime options.

    • Mark as private Enable this to prevent sensitive data from being stored in shared caches. This adds the Private directive to the Cache-Control header. Then, set Send Headers to either Send both Cache-Control and Expires or Send only Cache-Control.

    • Send Headers. Select the headers you want to be sent to the client for use in downstream caching. If you also want to use Mark as private, you can't select Expires. Send same headers as origin lets you use the caching headers on your origin server. You'll need to manually modify them on your origin to ensure they contain the appropriate caching settings. For example, if you want to prevent sensitive data from being stored in shared caches, add the Private directive to your origin caching heading and disable Mark as private in this behavior.

  • Allow caching, require revalidation (no-cache). This allows downstream caching with a mandatory origin revalidation before a cached copy reaches the request sender. The standard, Allow caching setting only revalidates with the origin once the Caching maxage has been reached. However, this option forces the browser to send an If-Modified-Since GET 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 Modified response.

    • Mark as private Enable this to prevent sensitive data from being stored in shared caches. This adds the Private directive to the Cache-Control header.
  • Don't allow caching (bust). This sends cache-busting headers downstream to prohibit downstream caching.

  • Pass cacheability headers from origin. This applies your origin server's Cache-Control or Expires header settings to downstream clients, to determine how caching should be applied downstream. Your origin cache headers are unchanged when they're passed to clients.

  • Don't send cacheability headers; client browser defaults apply. No caching headers are sent and client browsers cache content according to their default settings. The default settings may vary from browser to browser.

Mark as private and Resource Optimizer

If you're also using Resource Optimizer via Adaptive Acceleration, it doesn't support the Private directive in the Cache-Control header on your origin server. Typically, you should be making sure that PII won't ever be included on your origin server where it could be cached, which is why Mark as private is disabled by default, for both the Allow caching (Default) and Allow caching, require revalidation (no-cache) options. Talk to your ​Akamai​ account team if you need to enable this option and use Resource Optimizer in your Ion property.

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 Expires header; each option listed below sets the Expires header to a specific value.

Name

Description

(Default) Smaller value: origin header or remaining edge TTL

This sets the downstream caching lifetime to either the remaining Caching maxage or the origin header value, whichever is less. For the origin header, the process reviews either the Cache-Control:max-age or Expires header. If both are present what's set for Cache-Control:max-age takes precedence.

Greater value: origin header or remaining edge TTL

This sets the downstream caching lifetime to either the remaining Caching maxage or the origin header value, whichever is more. For the origin header, the process reviews either the Cache-Control:max-age or Expires header. If both are present what's set for Cache-Control:max-age takes precedence.

Remaining edge TTL

This sets the downstream caching lifetime to the remaining Caching maxage. Ion applies this value in the origin server's Expires header.

Full edge TTL (max-age)

This sets downstream caching lifetime to the full time currently set for the Caching maxage. Ion applies this value in the origin server's Expires header.

Fixed value

This lets you set the downstream caching lifetime to a custom fixed value. You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000. Ion applies this value in the origin server's Expires header.

Calculate Expires from origin Cache-Control

This sets the downstream caching lifetime to what's set as your origin server’s Cache-Control:max-age header value.


Set up CSS and Javascript

Recommended

CSS and JavaScript components can be critical for your site or app. We include this sub-rule by default to specifically apply caching settings for these file formats.

It's default set to keep CSS and JavaScript files in cache for a maximum of seven days.

What's set here overrides anything that's been set for generic Caching. Check what you have set there before you update settings in this Caching behavior. You should also review the demand and change frequency for these file formats in your environment before deciding on a different caching setting.

Use your origin settings for caching

If you know your origin server has been set up to apply proper caching settings for these file types, using either the Cache-Control or Expires headers, you can tell Akamai to use these settings instead. Click Caching option and select any of these options:

  • Honor origin Expires to use the Expires header.
  • Honor origin Cache-Control to use the Cache-Control header.
  • Honor origin Cache-Control and Expires to have ​Akamai​ check for either. If both exist, the Cache-Control header takes precedence.

Skip caching

If you don't want to cache these file formats, click Caching option and select any of these options:

  • No store. CSS and JavaScript files associated with your site won't be cached on edge servers.
  • Bypass cache. CSS and JavaScript files won't be cached and downstream caching will be blocked, too.

Every request for CSS or Javascript files will be sent to your origin server to get the latest version of these files for your site or app.

📘

This goes against the recommended practice. ​Akamai​ suggests that you apply some form of caching for your content to help expedite delivery to your end users.

Revalidation

If the Maxage comes to an end, you can have Ion try to revalidate your content. Use Force revalidation of stale objects to decide how you want to handle this:

  • Serve stale if unable to validate. Once the Maxage period ends and a request for CSS or JavaScript content comes in, Ion will try to connect with your origin server to check the status of this content. If it validates that new content is available, it will deliver it. If it can't validate, Ion will continue to serve the last known, good versions of these files.

  • Always revalidate with origin. Same as above. However, if Ion can't perform the validation, it will return an HTTP 403 error.


Set up Fonts

Recommended

Fonts go a long way in creating a unique look for your website and promoting readability. We include this sub-rule by default to specifically apply caching settings for some common font file formats that you may use on your site.

It's default set to keep common font file formats.eot, .woff, .woff2, otf, and .ttfin cache for a maximum of 30 days.

What's set here overrides anything that's been set for generic Caching. Check what you have set there before you update settings in this Caching behavior. You should also review the demand and change frequency for these file formats in your environment before deciding on a different caching setting.

Add a new font format

If you're using other font file formats on your site, simply click in the match field, type the file extension (without the period), and select {extension} (new item) from the drop-down.

Use this sub-rule

This rule works in the same way as the CSS and JavaScript sub-rule. It has the same recommendations and limitations on use, too.


Set up Images

Recommended

Images can be more important than text on some websites. We include this sub-rule by default to specifically apply caching settings for some common image file formats that you may use on your site.

It's default set to keep common font file formats.jpg, .jpeg, .png, gif, .webp, jp2, .ico, .svg and .svgzin cache for a maximum of 30 days.

What's set here overrides anything that's been set for generic Caching. Check what you have set there before you update settings in this Caching behavior. You should also review the demand and change frequency for these file formats in your environment before deciding on a different caching setting.

👍

Some of the forms of compression you can include in your Ion property recommend against the compression of images (for example, gzip with Last Mile Acceleration). If you're limited to using this compression, you should at least apply caching for your images to help speed up delivery.

Add a new image format

If you're using other image file formats on your site, simply click in the match field, type the file extension (without the period), and select {extension} (new item) from the drop-down.

Use this sub-rule

This rule works in the same way as the CSS and JavaScript sub-rule. It has the same recommendations and limitations on use, too.


Set up Files

Recommended

Files include downloadable assets you may offer on your site for your end users. We include this sub-rule by default to specifically apply caching settings for some common file formats that you may use on your site.

It's default set to keep some common file formats.pdf, .doc, .docx, and .odtin cache for a maximum of 7 days.

What's set here overrides anything that's been set for generic Caching. Check what you have set there before you update settings in this Caching behavior. You should also review the demand and change frequency for these file formats in your environment before deciding on a different caching setting.

❗️

Files containing Personal Identified Information (PII) should not be cached.

Add a new file format

If you're using other file formats on your site, simply click in the match field, type the file extension (without the period), and select {extension} (new item) from the drop-down.

Use this sub-rule

This rule works in the same way as the CSS and JavaScript sub-rule. It has the same recommendations and limitations on use, too.


Set up Other static objects

Recommended

This sub-rule serves as a catch-all for several other remaining file formats that are commonly found on a website or app. We include this sub-rule by default to specifically apply caching settings for these file formats.

It's default set to keep these file formats in cache for a maximum of 7 days.

What's set here overrides anything that's been set for generic Caching. Check what you have set there before you update settings in this Caching behavior. You should also review the demand and change frequency for these file formats in your environment before deciding on a different caching setting.

Add a new file format

If you're using other font file formats on your site, simply click in the match field, type the file extension (without the period), and select {extension} (new item) from the drop-down.

Use this sub-rule

This rule works in the same way as the CSS and JavaScript sub-rule. It has the same recommendations and limitations on use, too.


Set up HTML pages

Recommended, for non-NetStorage Origin Servers

This sub-rule works differently than the previous caching sub-rules. It's intended to identify common HTML-related components that should not be cached.

📘

This sub-rule is preconfigured for custom or third-party origin servers. You'll need to use different settings if you're using NetStorage.

It's preset to identify the following file formats, .html, .htm, .php, .jsp, .aspx, and EMPTY_STRING, which applies to all file types that don't include a file extension. The Caching option is set to No store, which means that these HTML file types are served from your origin, and if any versions are found in the edge server cache, they're cleared.

Since these types of files can change regularly for a site or app, we recommend that you keep them out of the edge server cache. Your origin server should be checked for updated content with each request.

There are exceptions

Notice that the Cache Key Query Parameters behavior is here as well. If a request comes in with any of these values set in its query string, the No store caching setting for these HTML file types is ignored, and the Caching option setting that's applied for generic Caching is used. All of the defaults are parameters used for tracking or analytics:

  • gclid. This is the Google click ID parameter. It's used to track outbound links from Google. For example, if a user performs a Google search and clicks a link that takes them to your site, this is applied as a query string parameter in that link.

  • fbclid. This is the Facebook click ID parameter. It's used to track outbound links from Facebook. For example, if a user clicks a link on Facebook that takes them to your site, this is applied as a query string parameter in that link.

  • utm_source. This is a Google Analytics parameter that tells you what the source of your traffic is, such as “google” “Instagram” or “twitter.” It gives you specific information regarding the websites that are referring your traffic.

  • utm_campaign. This is a Google Analytics parameter that provides the name of a specific marketing campaign. It's typically used to track the efficiency of the campaign.

  • utm_medium. This is a Google Analytics parameter that defines which medium a visitor used to find your site or app. Example values include "social," "email," or "cpc" (cost per click).

  • utm_content. This is a Google Analytics parameter that lets you know what call-to-action links brought in traffic. It's typically used to differentiate similar call-to-action content or links.

This sub-rule and NetStorage

If you're using NetStorage as your origin server, you can't use the default settings applied here:

  • Caching. No store and Bypass cache aren't supported with NetStorage. You need to apply some form of caching. Set a Maxage to at least 10 minutes for best performance.

  • Cache Key Query Parameters. These aren't supported with NetStorage. This needs to be set to Exclude all parameters.


Set up Redirects

Optional

Use this behavior to optionally configure caching for HTTP redirects. Redirects may occur because of an issue with your origin. If one becomes necessary, you may want to cache that redirect to limit hits to your origin server.

So, set the Enable slider in Cache HTTP Redirects to either of the following:

  • Disabled. This is the default and what's recommended. ​Akamai​ reads from the Cache-Control or Expires headers on your origin server to determine how to cache redirects.

  • Enabled. A redirect is cached on edge servers for the same time to live (TTL) as a successful 200 HTTP response for your content.

Set Chase Redirects

On occasion, a redirect may lead to another redirect. Use this behavior to decide if you want a request to "chase" down a chain of multiple redirects.

  • Enable. Left at the default of Off, if you enable Cache HTTP Redirects, ​Akamai​ will cache the first redirect it comes across, and continue to send that redirect for future requests. Set it to On to set up a chase, and configure a Chase Limit and whether or not you want to Serve 404.

  • Chase Limit. Use this to set the total number of redirects you want to follow. If a valid redirect is encountered before the limit is reached, it's served. Caching is applied as follows:

    • Cache HTTP Redirects is enabled. ​Akamai​ caches that redirect once it's reached and continues to send it for future requests. This continues for the same TTL as a successful HTTP 200 response.

    • Cache HTTP Redirects is disabled. The Cache-Control or Expires headers are reviewed on your origin server and caching is applied, accordingly. If caching is enabled in these headers, ​Akamai​ caches the redirect and sends it for future requests. This continues for the same TTL as a successful HTTP 200 response. If it's disabled in the headers, no caching occurs and subsequent requests for your site or app start the redirect chase over again.

  • Serve 404. If the Chase Limit is reached and another redirect is encountered, the chase will stop and an HTTP 404 "Not Found" is returned. If it's disabled, the last redirect from the Chase Limit is served.


Set up POST responses

Optional

A request to view your site or app is typically issued by a simple GET operation. The end user's client sends the GET and your site or app is returned for viewing. Your site may also include sections where an end user can provide datasuch as shipping information for a purchase. This is sent in a POST operation from the client. POST operations also include a response that's sent back to the client, to either note successful receipt of the data, or if an error has occurred.

Leaving this at its default setting of Off, POST requests are passed straight to the origin where they're handled, and nothing is cached. You can use this behavior to override this and cache POST responses. Set Status to On and select one of the following from POST Body to define how and whether to use the POST message body as a cache key:

  • Ignore in cache key. This uses only the URL to cache the response.

  • Include an MD5 hash in cache key. This adds a string digest of the POST response data as a query parameter to the cache URL.

  • Include as a query parameter in cache key. This adds the raw request body as a query parameter to the cache key, but only if the POST request’s Content-Type is application/x-www-form-urlencoded. You can use this in conjunction with Cache ID Modification behavior to define relevant query parameters.


Set up GraphQL

Optional (Requires specific third-party support)

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in an API and lets clients ask for exactly what they need, and nothing more. For example, if you have a weather application that returns all weather forecast information for a city and you just want to obtain the temperature for that city, GraphQL efficiently provides you with that information.

Prerequisites

  • Your site or app needs to support GraphQL. This is an optional form of caching that you can add only if your application supports GraphQL. Otherwise, leave it set to Off and stick to the standard Caching behavior and content-specific caching sub-rules.

  • The Allow POST behavior needs to be enabled. This is enabled by default in the Allowed methods sub-rule in Strengthen security rule.

  • Caching needs to be completely enabled. You need to have some form of generic Caching enabled. You can't have it set to No store or Bypass cache. Also, any of the other caching sub-rules used to override the generic Caching need to apply some form of caching, too. Most of these sub-rules are preset to apply caching. However, the HTML pages sub-rule is set up to block caching of specific assets. If you want to use GraphQL, you'll need to enable some form of caching here, or disable this sub-rule.

  • Define the scope for GraphQL caching. You need to post GraphQL queries under a specific path. You do this by setting up a Match criteria for the path. This sub-rule already has this preset to use a Path that matches on /graphql.

Configure the rule

Set the options in this behavior as necessary to enable GraphQL:

  • Enable. If you've met all of the Prerequisites, set this slider to On.

  • Cache 2xx Responses with GraphQL Errors. Set this to On if you want to cache responses that contain GraphQL errors. If your GraphQL server returns temporary errors with HTTP status code of 2xx, set this to Off.

  • Query Processing Failure Action. Select an action that should be taken if an edge server encounters an error while processing a GraphQL query during a POST reequest. If your GraphQL server doesn't allow mutations and subscriptions, set this to Apply Caching behavior for better offload.

  • Custom Query Parameter Name. If your origin server accepts GraphQL queries passed in a URL query parameter other than the default of "query," specify the appropriate name here. This only applies to GET requests.

  • Custom Body Parameter Name. If your origin server accepts GraphQL queries passed in the “JSON body parameter” field other than the default value of "query," specify the appropriate name here. This only applies to POST requests.

GraphQL caching limits

The following limitations apply for all GraphQL requests:

  • When caching GraphQL queries, the maximum allowed size of a query is 4096 bytes.
  • When caching GraphQL queries, the maximum allowed nesting depth is 100 levels.
  • When processing payload error handling, the maximum allowed size for a response payload is 1024 bytes.

Purge GraphQL queries

GraphQL currently supports the following query purging options:

📘

Purge content by URL or ARL is not supported.


Set up Uncacheable objects

This sub-rule is included to determine what to do with content that's identified as "uncacheable," in regards to applying Downstream Caching for the last mile of the request. Downstream caching refers to the caching instructions that an end user's client, such as a browser or mobile app should follow.

The rule is preset to recognize uncacheable content and turn off Downstream Caching for it:

  1. A request comes in to your origin for content that's identified as uncacheable.

  2. Uncacheable content is listed in the Edge-Control header on edge servers.

  3. The edge server sends a cache-busting header in the response to the client.

  4. Downstream Caching is turned off for this content on the client.

  5. Future requests from the same client will be directed to the origin server to get the content. (For example, to comply with potential updates or changes to it.)

  6. Requests for the same content from different clients will be fielded by edge servers where the Edge-Control header is read to identify uncacheable content and respond accordingly.

How to mark content as uncacheable

This is done at the origin server. Any of your content that includes the NO_STORE or BYPASS_CACHE HTTP headers is considered uncacheable.


Did this page help you?