All posts

Proper ETag Support Finally Arrives in the AEMaaCS Dispatcher

Daniel Strmečki

Reducing unnecessary network traffic is a core goal of HTTP caching, and one of the most effective mechanisms for achieving this has been part of the protocol for decades. ETags allow different layers of the web stack to determine whether a resource has actually changed before transferring it again, making them a powerful tool for improving performance and cache efficiency.

In modern architectures where browsers, CDNs, reverse proxies, and origin applications all participate in content delivery, ETags play an important role in enabling efficient validation of cached content. Instead of repeatedly sending the same payload across the network, each layer can simply verify whether the cached representation is still valid.

Despite this being a fundamental HTTP capability, many AEM implementations have historically not been able to fully benefit from ETag validation across the entire delivery stack. While the mechanism worked correctly in some parts of the architecture, there was a particular AEM cache layer where the expected behavior did not occur. To understand why, it is useful to first revisit how ETags work and how they are intended to operate across multiple caching layers.

What an ETag Actually Does

An ETag (Entity Tag) is an HTTP response header that acts as a unique fingerprint of a resource. The origin server generates this value and sends it together with the response. The identifier usually represents a hash or digest of the content, although the exact implementation can vary.

When a client later requests the same resource again, it can include the previously received value in an If-None-Match request header. If the resource has not changed, the server simply responds with a 304 Not Modified status. This response contains only the headers and no response body, indicating that the client can continue using its cached version instead of downloading the resource again. Although this interaction is often explained as a browser-to-server optimization, the mechanism is actually designed to work across every caching layer involved in delivering a response. Browsers, CDNs, reverse proxies, and origin applications can all participate in ETag validation.

How conditional requests work with ETag and If-None-Match headers

When implemented correctly, each layer can verify whether its cached representation is still valid before requesting or transferring the full resource. Instead of repeatedly sending the same content across the network, the system only exchanges lightweight validation requests. For frequently requested resources such as HTML pages or API responses, this can significantly reduce bandwidth usage and improve response times, particularly in large distributed architectures.

Where the AEM Delivery Chain Broke Down

In most modern web stacks, ETag validation works naturally across the entire delivery path. A browser sends conditional requests, intermediary caches evaluate them, and the origin server only returns the full response if the content has actually changed. In AEM environments, however, the flow historically stopped at Dispatcher. Browsers were able to store ETags and send validation requests, and CDNs were capable of forwarding those requests upstream. The problem appeared at the next step of the chain. When a CDN forwarded a request containing If-None-Match, Dispatcher did not properly evaluate the header against its cached response.

This meant that when cached content expired at the CDN layer and the CDN revalidated the resource with the origin stack, Dispatcher would still return the full response body instead of responding with 304 Not Modified when the content had not changed. As a result, unchanged content was repeatedly transferred from Dispatcher to the CDN after each CDN TTL expiration. The browser-to-CDN interaction behaved correctly, but the CDN-to-Dispatcher interaction did not benefit from the same validation mechanism. In large environments where CDNs frequently revalidate content, this meant that significant amounts of unnecessary traffic continued flowing through the system even when nothing had changed.

Generating ETags in AEM

For ETag validation to work, the origin application, in our case AEM, still needs to generate the ETag values in the first place. AEM does not automatically generate ETags for all responses, so custom implementations typically rely on a filter that calculates a digest of the response content and attaches it as an ETag header.

A well-known example of this approach can be found in ACS AEM Commons, which includes an ETag filter implementation that calculates a message digest of the outgoing response. This type of filter remains an important part of the overall setup because ETags still need to be generated somewhere, and in most cases the origin server is the better place to do it. Although Dispatcher can generate ETags, the application layer is usually in the best position to define them based on the actual response content, while Dispatcher should focus on correctly handling the conditional requests that depend on those headers.

The Dispatcher Enhancement

With AEMaaCS SDK version 2026.2.24464, Adobe introduced improved handling of conditional requests involving ETags in Dispatcher. The functionality is currently controlled through the following environment variable:

  • INTERNAL_AEM_DISPATCHER_ETAG_ENHANCEMENT=true

Once enabled, Dispatcher properly evaluates If-None-Match headers against cached responses and can return 304 Not Modified when the resource has not changed. When gzip compression is enabled in Dispatcher, the response ETag header may include a -gzip suffix added by Dispatcher. For conditional requests, however, the If-None-Match header should contain the original ETag value without this suffix, otherwise the comparison may not match correctly.

Example conditional request towards Dispatcher on AEMaaCS

This allows conditional request validation to function correctly between the CDN and Dispatcher layers, which historically was the missing part of the chain. Instead of sending the full response body whenever a CDN revalidates expired content, Dispatcher can now confirm that the cached resource is still valid, allowing the CDN to continue using its stored version without transferring the entire payload again.

Conclusion

ETags are one of the most fundamental optimization mechanisms built into HTTP, yet until now AEM architectures had a blind spot where the validation chain stopped at Dispatcher. Browsers and CDNs were capable of performing conditional requests, and AEM could generate ETag headers, but Dispatcher was not able to evaluate those requests against its cached responses.

With the recent Dispatcher update that missing piece is finally addressed. Once the feature flag is enabled and ETags are generated by the application layer, conditional request validation can function correctly across the entire delivery stack. This change was implemented following a feature request we raised with Adobe, and it is great to see the platform evolve based on real-world use cases from the community. Even though the change is small from a configuration standpoint, it allows a long-established HTTP capability to finally work as intended within AEM deployments.

Filed underAEMCachingCDN
All posts

Blog

All posts

If these challenges sound familiar, explore how we help enterprises reduce risk.