ETags and conditional requests for faster, safer APIs
Short answer: An ETag is a short identifier your server sends with a response that changes whenever the content changes. When an app or browser asks for the same thing again, it sends the ETag back, and if nothing has changed the server answers with a tiny 304 Not Modified instead of the full data. That saves bandwidth and battery for mobile apps polling your API, makes pages and feeds faster, and, combined with If-Match on updates, lets your API refuse to overwrite changes someone else made in the meantime.
The problem: sending the same data again and again
Many business apps fetch the same data repeatedly: a mobile app refreshing a product catalogue every time it opens, a dashboard polling an order list every 30 seconds, a partner integration pulling your price list each hour. Most of the time nothing has changed, but the full response travels every time.
For customers on mobile data, that means slower screens and more battery use. For you, it means more server work and data transfer.
How ETags and conditional requests work
MDN's documentation for the ETag header describes it as an identifier for a specific version of a resource; if the resource at a URL changes, a new ETag value must be generated. The flow:
- The client requests a resource. The server responds with the data and an ETag header, such as a hash of the content or a version number.
- Next time, the client sends the stored value in an If-None-Match header.
- If the resource has not changed, MDN's guide to conditional requests explains that the server sends back a 304 Not Modified response, and the client uses its cached copy. If it has changed, the server sends the new data with a new ETag.
The guide notes that the round trip still costs something, but it is more efficient than transmitting the whole resource again.
An older, date-based alternative uses Last-Modified on responses and If-Modified-Since on requests. ETags are usually more precise, because a timestamp can miss several changes within the same second and depends on clocks.
Strong and weak ETags
MDN explains that a W/ prefix marks a weak validator. Weak ETags are easy to generate but far less useful for comparisons; strong validators are ideal for comparisons but can be difficult to generate efficiently. The HTTP specification, RFC 9110, uses the same distinction.
In practice:
- A weak ETag says "semantically the same", for example a version number of a record where formatting might vary. Fine for caching.
- A strong ETag says "byte-for-byte identical", such as a hash of the exact response body. Needed for some operations such as resuming downloads.
Be aware that some servers and proxies compress responses and may change or weaken ETags along the way, so test the full path.
Generating ETags in your API
Good sources of an ETag value:
- A version column on the database record, incremented on each update. Cheap and reliable for single records.
- The last-updated timestamp plus ID for simple cases, ideally with high precision.
- A hash of the response body. Simple to add in middleware, and many frameworks do this automatically for responses, but the server still has to build the response before it can compare, so it saves bandwidth more than server work.
- For lists, a combination of the latest update time and the item count, or a version number for the whole collection maintained when any item changes.
Make sure the ETag changes whenever anything in the response changes, including fields from related records you include, such as a product's current stock.
Preventing lost updates with If-Match
ETags also help with writes. MDN's ETag documentation describes avoiding "mid-air collisions": the client sends the ETag it received in an If-Match header with its update, and if the resource has changed in the meantime, the server responds with 412 Precondition Failed instead of applying the update. The conditional requests guide describes this as preventing lost updates when modifying a document on the server.
This gives partners and mobile apps a standard way to say "only save this if nobody else has changed it", using the same headers they already handle for caching.
Making clients use them
- Browsers handle ETags automatically for normal requests.
- Mobile apps: many HTTP libraries cache and revalidate automatically when caching is enabled; others need you to store the ETag and send If-None-Match yourself.
- Partners and integrations: document the behaviour in your API guide, including 304 and 412 responses, so they can benefit.
- Combine with Cache-Control so clients know how long they can reuse data without even asking.
Testing
Use your browser's network tools or a command-line HTTP client to make a request, copy the ETag, then repeat the request with If-None-Match and confirm you get a 304 with no body. Then change the record and confirm the next request returns 200 with a new ETag. For updates, send an If-Match with an outdated value and confirm you get 412.
A worked example
Picture a hypothetical Calgary equipment-rental company whose mobile app downloaded the full rental catalogue, several hundred items with images listed, every time staff and customers opened it. The data rarely changed during the day.
The developers added a catalogue version number, updated whenever any item changed, and returned it as an ETag on the catalogue endpoint. The app stores the ETag and sends If-None-Match on each refresh, getting a 304 most of the time. Item update endpoints now require If-Match, returning 412 if the item changed since it was loaded. App start-up became noticeably faster on mobile data, and staff no longer overwrote each other's edits to rental rates.
FAQ
Do ETags replace caching headers?
No. Cache-Control decides how long a copy can be reused without asking; ETags make the asking cheap.
Do CDNs support ETags?
Generally yes, though some modify them when compressing. Check yours.
Should every endpoint have ETags?
Prioritise frequently fetched, rarely changing data and records that are edited by several people.
If your app keeps downloading the same data or users overwrite each other's changes, tell us about your API.