Test ETag caching with curl: send If-None-Match and get 304 Not Modified

To check that a server supports conditional requests, fetch the resource once, copy its ETag header, and send it back in If-None-Match: curl -i -H 'If-None-Match: "ETAG"' URL. A server that implements it answers 304 Not Modified with no body while the resource is unchanged, and 200 OK with the full body after it changes. curl 7.68 and later can do the bookkeeping with --etag-save FILE and --etag-compare FILE.

Try it against a local server

The server below computes a strong ETag from the body and honours If-None-Match:

cat > server.js <<'EOF'
const http = require("http");
const crypto = require("crypto");
const body = '{"items":[1,2,3]}\n';
const etag = '"' + crypto.createHash("sha1").update(body).digest("hex").slice(0, 12) + '"';
http.createServer((req, res) => {
  res.setHeader("ETag", etag);
  res.setHeader("Cache-Control", "no-cache");
  if (req.headers["if-none-match"] === etag) { res.writeHead(304); return res.end(); }
  res.setHeader("Content-Type", "application/json");
  res.end(body);
}).listen(5207, "127.0.0.1");
setTimeout(() => process.exit(0), 10000);
EOF
node server.js &
sleep 1
etag=$(curl -s -I http://127.0.0.1:5207/items | tr -d '\r' | awk 'tolower($1)=="etag:" {print $2}')
echo "ETag: $etag"
echo "== matching ETag"
curl -s -i -H "If-None-Match: $etag" http://127.0.0.1:5207/items | tr -d '\r' | grep -iE '^(HTTP|etag|content-length)'
echo "== stale ETag"
curl -s -o /dev/null -w '%{http_code}\n' -H 'If-None-Match: "old"' http://127.0.0.1:5207/items
echo "== curl keeps the ETag in a file"
curl -s -o items.json --etag-save etag.txt http://127.0.0.1:5207/items
curl -s -o items.json -w '%{http_code}\n' --etag-compare etag.txt http://127.0.0.1:5207/items
wait

ETag: "c2792215b282"
== matching ETag
HTTP/1.1 304 Not Modified
ETag: "c2792215b282"
== stale ETag
200
== curl keeps the ETag in a file
304

The first request with the matching ETag gets 304 and the same ETag header; a stale value gets the full 200 response. With --etag-compare, curl reads the saved value and sends it as If-None-Match for you.

Headers involved

Last-Modified instead of ETag

For servers that only send Last-Modified, use curl -z "date" URL or curl -z file URL: curl sends If-Modified-Since with that date (or the file's modification time), and a server that supports it returns 304 for unchanged content.

Pitfalls

• The quotes belong to the ETag. If-None-Match: abc does not match ETag: "abc".
• Compression can change the ETag: some servers append a suffix such as -gzip or make the tag weak (W/) when they compress, so a value captured without Accept-Encoding may not match a browser request.
• Cache-Control: no-store tells clients not to keep the response at all, so browsers will never send If-None-Match; see no-cache vs no-store.

FAQ