eCDN Cache Rules

Cache rules allow you to control which content is eligible for caching at the eCDN. By default, eCDN only caches based on file extension and does not cache HTML pages or JSON responses. Cache rules enable you to make these previously uncacheable resources eligible for edge caching, which is a prerequisite for using cache purging by tags or paths.

Cache rules make content eligible for caching, but do not force caching. Your origin server must send appropriate Cache-Control headers for content to actually be cached. When a cache rule matches a request, eCDN evaluates specific conditions to determine whether to cache the resource.

eCDN does not cache the resource if a cache rule matches and any of the following conditions are true:

The Cache-Control header is set to private, no-store, no-cache, or max-age=0.
No Cache-Control header is present.
The Set-Cookie header exists.
The HTTP request method is anything other than GET.

eCDN does cache the resource if a cache rule matches and all of the following conditions are true:

The request method is GET.
No Set-Cookie header is present.
Either the Cache-Control header is set to public and max-age is greater than 0, or the Expires header is set to a future date.
- If both max-age and an Expires header are set, max-age takes precedence.
- If s-maxage is present, it takes precedence over max-age.

For more resources on caching in general, refer to the following resources:

eCDN caches content based on file extension (not MIME type).

By default, eCDN caches the following file extensions:

Supported formats:

7Z, AVI, AVIF, APK, BIN, BMP, BZ2
CLASS, CSS, CSV, DOC, DOCX, DMG
EJS, EOT, EPS, EXE, FLAC, GIF, GZ
ICO, ISO, JAR, JPG, JPEG, JS
MID, MIDI, MKV, MP3, MP4, OGG, OTF
PDF, PICT, PLS, PNG, PPT, PPTX, PS, RAR
SVG, SVGZ, SWF, TAR, TIF, TIFF, TTF
WEBM, WEBP, WOFF, WOFF2
XLS, XLSX, ZIP, ZST

If your content has an extension that is not in the preceding list, use cache rules to make it eligible for caching. eCDN does not cache HTML, JSON, XML, or TXT files, except robots.txt.

The maximum cacheable file size is 5 GB.

Parameter	Type	Description
`description`	string	A description of the cache rule.
`expression`	string	A rule expression that defines when to apply the rule. Must use supported fields as described in the Supported Expression Fields section. Maximum length: 4096 characters.
`action`	string	The action to perform. Currently, only `cache` is supported.

Parameter	Type	Default	Description
`enabled`	boolean	`true`	Whether the rule is enabled.
`excludeQueryStrings`	array of strings	`null` (all query strings included)	List of query string parameters to exclude from the cache key. If provided, must be non-empty. Use empty array `[]` in PATCH to clear existing exclusions.
`ignoreQueryStringsOrder`	boolean	`false`	If `true`, query strings are sorted alphabetically before creating the cache key. This means `?a=1&b=2` and `?b=2&a=1` share the same cache entry.
`respectStrongEtags`	boolean	`false`	If `true`, eCDN uses strong ETag header validation to ensure that resources in the cache and on the origin server are byte-for-byte identical.
`position`	object	Last position	Specifies where to insert the rule in the ruleset. Must specify either `before` or `after` with a rule ID. Cache rules are evaluated in the order they appear in the ruleset. Multiple cache rules can match the same request, and the last matching rule wins.

Cache rule expressions use the same operators and functions as rate limiting rules and custom rules, but support a different set of fields. For more information on the supported operators and functions, see Rule Expression in the eCDN Rate Limiting Rules guide.

Cache rule expressions support the following fields:

Field	Description	Usage in Expression	Type	Example
URI Full	Represents the full URI as received by the web server.	`http.request.full_uri`	String	`http.request.full_uri eq "https://www.example.com/path/index?section=123456&expand=comments"`
URI	Represents the URI path and query string of the request.	`http.request.uri`	String	`http.request.uri eq "/path/index?section=123456&expand=comments"`
URI Path	Represents the URI path of the request.	`http.request.uri.path`	String	`http.request.uri.path eq "/path/index"`
URI Query String	Represents the entire query string, without the `?` delimiter.	`http.request.uri.query`	String	`http.request.uri.query eq "section=123456&expand=comments"`
URI Path Extension	The lowercased file extension in the URI path without the dot (`.`) character.	`http.request.uri.path.extension`	String	`http.request.uri.path.extension eq "html"`
Host Name	Represents the host name used in the full request URI.	`http.host`	String	`http.host eq "www.example.com"`
Cookie	Represents the entire cookie as a string.	`http.cookie`	String	`http.cookie eq "session=8521F670545D7865F79C3D7BEDC29CCE;-background=light"`
Request Cookies	The `Cookie` HTTP header associated with a request represented as a Map (associative array).	`http.request.cookies`	`Map<String>\Array`	`any(http.request.cookies["app"][*] eq "test")`
HTTP Headers	Represents HTTP request headers as a Map (or associative array).	`http.request.headers`	`Map<String>\Array`	`any(http.request.headers["content-type"][*] eq "application/json")`
HTTP Referer	Represents the HTTP Referer request header, which contains the address of the web page that linked to the currently requested page.	`http.referer`	String	`http.referer contains "www.example.com"`
User Agent	Represents the HTTP user agent, a request header that contains a characteristic string to allow identification of the client operating system and web browser.	`http.user_agent`	String	`http.user_agent eq "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.61 Safari/537.36"`
X-Forwarded-For	The full value of the `X-Forwarded-For` HTTP header.	`http.x_forwarded_for`	String	`http.x_forwarded_for eq "203.0.113.195, 70.41.3.18"`
SSL/HTTPS	Returns true when the HTTP connection to the client is encrypted.	`ssl`	Boolean	`ssl`

Match specific path pattern using regex:

Match on file extension type:

Combine conditions:

Explicitly exclude certain paths:

This endpoint creates a cache rule in the specified zone.

A maximum of 200 cache rules is allowed in a single zone.

Sample success response: 201 HttpStatus code response body contains the cache rule that was created.

This endpoint returns all of the cache rules in the specified zone in order of priority. If no cache rules exist, an empty array [] is returned (not 404).

Sample success response: 200 HttpStatus code response body contains all of the cache rules in the specified zone.

excludeQueryStrings is only included in the response when query strings are explicitly excluded. If all query strings are included in the cache key, this field is omitted from the response.

This endpoint updates the requested cache rule. If the requested rule does not exist, a 404 Not Found response is returned.

You must provide at least one cache rule parameter in the request body.
In the scenario where you have set excludeQueryStrings but wish to remove it (and thus have all query strings included in the cache key), you must include "excludeQueryStrings": [] in the request body to clear the value.

Sample success response: 200 HttpStatus code response body contains the requested cache rule.

This endpoint deletes the requested cache rule. If the requested rule doesn't exist, a 404 Not Found response is returned.

Sample success response: 204 HttpStatus Code (No Content)

Deleting a rule doesn't purge cached content. Use the cache purge API if you need to immediately invalidate cached content.

Understand origin cache headers. Cache rules make content eligible, but origin must send the appropriate Cache-Control headers.
Start with specific rules. Begin with expressions scopes to specific pages and gradually expand.
Test in lower environments first. Always test cache rules in a development or staging environment before applying to production.
Use cache tags. Set Cache-Tag headers from origin to enable tag-based purging.
Exclude specific query strings. Use excludeQueryStrings to prevent cache fragmentation from tracking parameters and increase cache hit ratios.
Monitor cache hit ratios using BM Analytics or Logpush. Use the Analytics tab in Business Manager to monitor cache performance by viewing cache statuses. Alternatively, use eCDN Logpush to monitor logs and view cache statuses, response times, and more.

Caching authentication endpoints or personalized content. Avoid caching paths like /login, /account, /cart, etc. that contain user-specific data. Ensure origin sends the correct headers private, no-store, no-cache, or max-age=0 or explicitly exclude the paths from any cache rules.
Overly broad expressions. Avoid expressions that are too broad and match all traffic. Use specific path patterns instead.
Assuming content will be cached. Cache rules make content eligible, but content is only cached if:
1. Origin sends Cache-Control: public, max-age=X (where X > 0).
2. No Set-Cookie header is present.
3. Request method is GET.
After enabling caching, eligible requests are served from eCDN cache. Keep in mind when monitoring system statistics that these requests won't reach the origin.

PWA Kit serves server-side rendered HTML product pages that aren't cached by default. Create a cache rule to make product pages eligible for caching. For more information about improving performance for PWA Kit storefronts, see Maximize Your Cache Hit Ratio.

Sample cache rule:

SFRA content asset pages, landing pages, and marketing pages are HTML that you can cache.

Sample cache rule:

Cache rules make content eligible for selective cache purging using the existing cache purge API. After creating cache rules, you can purge cached content by path or by tag. For details, see cachePurge.

Purge by path:

Purge by tag:

Set Cache-Tag headers from your origin, then purge by tag.

Origin response headers:

Purge request:

CDN-API cache rules currently only support making content eligible for caching (action: "cache"). As a workaround, ensure your origin sends Cache-Control: private, no-store, no-cache, or max-age=0 for content that should not be cached. eCDN respects these headers and does not cache the content.

All matching rules are evaluated, and the last matching rule's settings take precedence.

No, cache rules respect origin Cache-Control headers.

No. eCDN only caches GET requests, regardless of cache rule configuration. Cache rules can match POST/PUT/DELETE requests, but those requests won't be cached. You don't need to filter by HTTP method in your expression because eCDN automatically only caches GET requests.

If you created a cache rule but content still hits the origin:

Check origin headers. Verify origin sends Cache-Control: public, max-age=X (where X > 0).
Check for Set-Cookie. Responses with Set-Cookie headers are not cached.
Verify request method. eCDN only caches GET requests.
Verify rule expression. Ensure expression matches your URL patterns.
Check rule is enabled. Verify enabled: true in rule response.
Check the response headers. Look for Cf-Cache-Status: HIT (cached) or MISS/DYNAMIC (not cached).

Check cache TTL. Reduce max-age in origin Cache-Control header.
Purge cache. Use cache purge API after content updates.
Verify query strings. Ensure query parameters that affect content aren't excluded.

excludeQueryStrings removes specific query parameters from the cache key. ignoreQueryStringsOrder sorts query parameters alphabetically before creating the cache key. You can use them together to normalize URLs with tracking parameters.

The rule is removed from the ruleset immediately. Previously cached content remains cached until:

TTL expires (based on origin Cache-Control: max-age).
Cache is purged manually via cache purge API.
Origin sends updated Cache-Control headers.

Deleting a rule doesn't purge cached content. Use the cachePurge API if you need to immediately invalidate cached content.