Edgio
Edgio Console

Cache Key

Our edge servers use cache keys to determine whether a cached response exists for a specific request. Specifically, they calculate a cache key for each request. They then use this cache key to check for a cached response.
View a request’s cache key through the x-ec-cache-key response header. By default, this header is excluded from the response.
Syntax: x-ec-cache-key: <CACHE KEY>
Example: x-ec-cache-key: //http/800001/web/21/images/foo.jpg:/hs-5041808438894094098.jpg
Learn how to generate this response header.

Customizing the Cache Key

If your web application relies on query string parameter(s), request header(s), or cookie(s) when generating a response, then you should customize the cache key to include those elements.
Key information:
  • Defining custom cache keys too broadly impacts performance and lowers your cache hit ratio.
    We strongly recommend that you restrict this customization to a specific set of traffic (e.g., dynamic responses) and only add the specific critieria that influence the response provided to the client.
    For example, if the response varies according to a single query string parameter, then you should only add that query string parameter to your cache key. Adding additional query string parameters may cause too much segmentation for your cached content and thus reduce your cache hit ratio.
  • Customize the cache key for a specific set of requests by implementing one of the following features within a rule or route:
    FeatureCDN-as-CodeDescription
    Cache Keycache_keyRecommended. Use this feature to customize the cache key through query string parameters, request headers, cookies, and custom metadata.
    Cache Key Query Stringcache_key_query_stringUse this feature if you need to include one or more query string parameters in the cache key.
    Rewrite Cache Keycache_key_rewriteAdvanced. Use this feature if you require precise control over how a cache key is calculated.
We strongly recommend that you limit cache key customization to one of the above features per rule. Applying multiple cache key features may produce unexpected results or cause too much segmentation for your cached content.

Sample Custom Cache Key Implementations

Examples of how to customize the cache key are provided below.

Query String Parameter Example

Restrict the cache key to only include the page and filters query string parameters using either of the following methods:
  • Rules: Create a rule that sets the Cache Key feature to Include Only the page and filters query string parameters.
    Cache Key feature example
  • CDN-as-Code:
    JavaScript./routes.js
    1export default new Router().always({
    2  caching: {
    3    cache_key: {
    4      include_query_params: ["page", "filters"],
    5    },
    6  },
    7});

Cookie Example

This example demonstrates how to apply a custom default cache key for requests to the marketing folder. A sample URL is provided below.
https://www.example.com/conferences/marketing/index.htm
Specifically, we will include the language and currency cookies within the cache key using either of the following methods:
  • Rules: Create a rule that defines:
  • CDN-as-Code:
    JavaScript./routes.js
    1export default new Router().match("/conferences/marketing/:asset", {
    2  caching: {
    3    cache_key: {
    4      include_all_query_params: true,
    5      include_cookies: ["language", "currency"],
    6    },
    7  },
    8});

Country Example

This example demonstrates how to add geolocation metadata to the cache key for requests to the marketing folder. A sample URL is provided below.
https://www.example.com/conferences/marketing/index.htm
Specifically, we will add the country from which the request originated to the cache key using either of the following methods:
  • Rules: Create a rule that defines:
  • CDN-as-Code:
    JavaScript./routes.js
    1export default new Router().match("/conferences/marketing/:asset", {
    2  caching: {
    3    cache_key: {
    4      include_all_query_params: true,
    5      include_expressions: ["%{geo_country}"],
    6    },
    7  },
    8});
Use feature variables when defining expressions. However, you may not use response metadata when defining a cache key.

Cache Key Reference

Your configuration determines how our edge servers construct the cache key.
Default Syntax:
//http/80<LEGACY AN>/<ORIGIN CONFIGURATION>/<DEPLOYMENT VERSION>/<HOSTNAME>/<RELATIVE PATH>:/[q-<QUERY STRING HASH>_]hs-<URI HASH>[<FILE EXTENSION>]
Cache Key Feature Syntax:
Edgio calculates the cache key as follows when the Cache Key feature is applicable to a request:
//http/80<LEGACY AN>/<ORIGIN CONFIGURATION>/<DEPLOYMENT VERSION>/<HOSTNAME>/cache-key-customization=<HASH>/<RELATIVE PATH>:/[q-<QUERY STRING HASH>_]hs-<URI HASH>[<FILE EXTENSION>]
Experimentation Syntax:
Edgio calculates the cache key as follows when the request is eligible for one or more experiment(s):
//http/80<LEGACY AN>/<ORIGIN CONFIGURATION>/<DEPLOYMENT VERSION>/<HOSTNAME>/cache-key-experiments=<HASH>/<RELATIVE PATH>:/[q-<QUERY STRING HASH>_]hs-<URI HASH>[<FILE EXTENSION>]
Definitions for the above placeholder values are provided below.
PlaceholderDescription
<LEGACY AN>Indicates your unique legacy customer account number.
<ORIGIN CONFIGURATION>Indicates the name of the origin configuration associated with the request.

CDN-as-code: Deploying a CDN-as-code configuration automatically generates the following system-defined origin configurations: edgio_static, edgio_permanent_static, edgio_serverless, and edgio_image_optimizer. Your rules determine on a per request basis which origin configuration will be applied to the cache key. View how Edgio maps your code to these origin configurations from the Rules page. Returns origin when an origin configuration is inapplicable to a request.
<DEPLOYMENT VERSION>The replacement value for this placeholder is determined during deployment through the Deploy Changes popup’s Purge the cache after deployment option.
  • Enabled: Indicates the version of the deployment for the configuration that served the request whose response was cached.
  • Disabled: Returns 0.
Learn how to configure this option.
<HOSTNAME>Indicates the request URL’s hostname.
<RELATIVE PATH>Indicates the relative path to the requested content. This relative path starts directly after the hostname.
<QUERY STRING HASH>Indicates a hash of the request’s query string. If the request URL does not contain a query string, then the cache key will exclude q-<QUERY STRING HASH>_.
Exclude the query string from the cache key through the Cache Key feature (cache_key).
<URI HASH>Indicates a hash of the request URI.
<FILE EXTENSION>Indicates the request’s file extension (e.g., .html). It is excluded from the cache key when the request URL does not contain a file extension.