WebTech1223411 logo WebTech1223411Web tech, read closely
Back-End

How ETags and Conditional Requests Cut API Load

Your API serves the same product list to thousands of clients every minute, and almost every response is identical to the one each client already has.

A developer's monitor showing an HTTP response panel with a 304 status and ETag header, next to a server rack diagram on a whiteboard

Your API serves the same product list to thousands of clients every minute, and almost every response is identical to the one each client already has. The server still queries the database, serializes 200 KB of JSON and pushes it over the wire, only for the client to discard it as unchanged.

Conditional requests fix this with two small headers. The server tags each response with an ETag, the client sends that tag back next time, and if nothing changed the server replies with an empty 304 Not Modified. Done well, it cuts bandwidth and often a large share of server work on read-heavy endpoints.

How ETags and conditional requests work

An ETag is an opaque identifier for one specific version of a resource. The server decides what it is. Clients only store it and send it back.

  1. The client requests GET /products/42. The server responds 200 with the body and a header such as ETag: "v3-a91f".
  2. The client caches the body and the tag.
  3. On the next request, the client sends If-None-Match: "v3-a91f".
  4. If the current version still has that tag, the server returns 304 with no body. If not, it returns 200 with the new body and a new ETag.

A 304 response is usually under 300 bytes of headers. Compared with a 50 KB JSON payload, that is a reduction of more than 99 percent in transfer for that request. Browsers handle all of this automatically. Mobile apps and server-to-server clients need it wired in, which most HTTP libraries support with a cache setting.

There is also a time-based variant using Last-Modified and If-Modified-Since. It works, but it only has one second resolution and breaks when the same content is regenerated with a new timestamp. ETags are more precise.

A CDN in front of the API benefits too. When an edge cache entry expires, the CDN revalidates with your origin using the stored ETag. A 304 from the origin lets the edge keep serving its copy, so a catalogue endpoint behind a CDN might send only a few hundred bytes per edge location per revalidation instead of the full payload. On a service with 30 edge locations revalidating every minute, that difference adds up to gigabytes per day.

Strong vs weak ETags

ETags come in two forms, and choosing the wrong one causes subtle bugs.

TypeFormatMeaningUse for
Strong"abc123"Byte-for-byte identicalDownloads, range requests, optimistic locking
WeakW/"abc123"Semantically the same, bytes may differJSON that may be reformatted or compressed differently

One common trap: some reverse proxies and compression layers convert strong ETags to weak ones, or strip them, when they gzip a response. If your 304 rate is zero in production but fine locally, check whether a proxy is rewriting the header.

Generating ETags without wasting the savings

The naive approach is to build the full response, hash it with something like SHA-1 or xxHash, and use the hash as the tag. Many frameworks do exactly this by default, including Express. It saves bandwidth but not server work, because you still query and serialize everything before discovering nothing changed.

Better options derive the tag from data you already have cheaply:

  • Version column. An integer incremented on every update. Tag becomes "42-v17". One indexed lookup, no serialization.
  • Updated timestamp. Use the row's updated_at with millisecond precision, combined with the ID.
  • Collection fingerprint. For lists, combine the count and the latest updated_at across the result set: one aggregate query instead of fetching 500 rows.
  • Cache key reuse. If you already cache rendered responses in Redis, the cache key or a version counter can double as the ETag.

Include anything that changes the output in the tag: API version, user role if fields differ by permission, and query parameters. Paginated endpoints need the page or cursor in the tag too, which ties in with choices covered in cursor vs offset pagination.

The counter-take: do not treat ETags as a free speed boost

Advice on API performance often says to "add ETags everywhere." I think that is wrong for two reasons.

First, on endpoints where content changes on almost every request, such as a live feed or a personalised dashboard, you pay the cost of computing tags and checking headers for a 304 rate near zero. That is pure overhead.

Second, ETags reduce transfer, not request count. Every client still makes the round trip. If your bottleneck is request volume rather than payload size, Cache-Control with a max-age does far more, because clients skip the request entirely until it expires. A product catalogue that updates hourly is better served with max-age=300 plus an ETag for revalidation than with an ETag alone.

Measure first. Log the share of responses that would have matched, and add ETags where that rate is above roughly 30 percent and the payload is larger than a few kilobytes.

Using If-Match to prevent lost updates

ETags also solve a write problem. Two clients load the same order, both edit it, and the second save silently overwrites the first. With optimistic concurrency, the client sends PUT /orders/42 with If-Match: "v17". If the current version is no longer v17, the server returns 412 Precondition Failed and the client knows to reload.

This replaces database locks for most web workflows and pairs well with the retry safety discussed in how idempotency keys stop duplicate API requests. Use strong ETags here, and make the version check and the write a single atomic operation, for example UPDATE with WHERE version equals the expected value.

A practical rollout checklist

  • Return ETag on GET responses for resources that change less often than they are read.
  • Honour If-None-Match on GET and HEAD, and If-Match on PUT, PATCH and DELETE.
  • Send Cache-Control alongside ETag. Use no-cache if clients must always revalidate, and private for user-specific data so shared caches do not store it.
  • Add Vary for headers that change the response, such as Accept-Encoding or Authorization.
  • Expose ETag through CORS with Access-Control-Expose-Headers if browser clients read it from JavaScript.
  • Track 304 rate per endpoint in your metrics so you can see whether it is paying off.

Conditional requests are one of those features that make an API pleasant to consume, alongside the design habits in designing a REST API other developers enjoy.

Frequently asked questions

What is the difference between ETag and Cache-Control?

Cache-Control tells the client how long it can reuse a response without asking the server. An ETag lets the client ask whether its stored copy is still valid once that period has passed. Most APIs benefit from using both together.

Does a 304 response count against rate limits?

That depends on the API. Many count every request, since the server still does some work, while others exempt 304 responses to encourage clients to revalidate. Document your choice so client developers know what to expect.

Should POST requests return an ETag?

A POST that creates a resource can return the new resource's ETag along with its location, which saves the client an extra GET. POST responses themselves are rarely cached, so conditional headers on POST are uncommon outside custom concurrency schemes.

KO
Kofi Oosterhuis

Kofi spent years keeping APIs and game servers alive through traffic spikes and the occasional bad deploy. He covers back-end design, scaling and networking, with a preference for boring systems that do not page anyone at night.

More posts by Kofi

More in Back-End

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto