Conditional GET

API Design

Meaning

Conditional GET is an HTTP request pattern where the client includes validators such as If-None-Match or If-Modified-Since to ask the server whether a cached resource has changed. It addresses the bandwidth and latency cost of re-downloading unchanged payloads on every poll or refresh. The trigger is any client that already holds a cached representation and wants to revalidate it cheaply before reusing or replacing it.

Primary Function

HTTP cache validation

Communicative Purpose

Avoids transferring unchanged response bodies by letting the server reply with 304 Not Modified when validators still match.

Pattern

send GET with If-None-Match and/or If-Modified-Since → server compares validators → respond 200 with body or 304 with empty body

Função primária

HTTP cache validation

Propósito comunicativo

Avoids transferring unchanged response bodies by letting the server reply with 304 Not Modified when validators still match.

Situações de gatilho

Web APIs: revalidating a cached JSON resource before rendering; CDN edge: checking origin freshness for a stale object; Browser fetches: revalidating HTML, JS, or images on reload or back-forward navigation.

Contextos

HTTP/REST APIs, browser caching, CDN edge logic, mobile clients with offline caches, RSS feed readers.

Padrão

send GET with If-None-Match and/or If-Modified-Since → server compares validators → respond 200 with body or 304 with empty body

Colocados típicos

ETag
Last-Modified
If-None-Match
If-Modified-Since
304 Not Modified
Cache-Control
Vary
max-age
stale-while-revalidate.

Substituições comuns

Unconditional GET (always returns full body
simpler but wastes bandwidth)
HEAD request (checks metadata only
no body comparison)
range request (partial fetch
different intent).

Erros comuns

Sending validators without a stored ETag or Last-Modified timestamp, causing the server to ignore them and return 200 — cause: client lost cache metadata; consequence: cache validation silently disabled. Treating 304 as an error and retrying — cause: misreading status codes; consequence: infinite revalidation loop. Comparing ETags with weak/strong mismatch (W/"abc" vs "abc") — cause: ignoring RFC 7232 weak comparison rules; consequence: spurious 200 downloads. Omitting Cache-Control: no-cache on the original response — cause: assuming validators alone are enough; consequence: intermediate caches may serve stale content without revalidating. Using If-Modified-Since with sub-second precision — cause: HTTP-date format only supports second resolution; consequence: server may ignore the header.

Similar / contraste

HEAD request: probes metadata without body but does not validate cached content; ETag: the opaque token used as a validator, not the request itself; Last-Modified: a timestamp-based validator, weaker than ETag; If-Match: precondition for safe updates, not cache revalidation.

Interferências

Coming from REST frameworks that auto-handle caching: developers may assume the client library always sends validators — must explicitly preserve ETag/Last-Modified from prior responses. Coming from browser devtools: the Network tab shows 304 as a separate row, leading some to think it is a different request type — it is still a GET, just with an empty body.

Família do chunk

ETag
Last-Modified
If-None-Match
If-Modified-Since
304 Not Modified
Cache-Control
Vary

Nuance

Do not use when the resource is uncached or when the server cannot compute validators cheaply (e.g. dynamic, non-deterministic responses). Performance impact is bandwidth proportional to body size — large JSON or media payloads benefit most, while tiny responses may cost more in round-trip overhead than they save. Boundary condition: 304 responses must include the same validators (ETag, Cache-Control, Expires, Vary) as the 200 would, so clients can update their cache metadata without a body.

Efeito pragmático

In production, conditional GETs cut API egress by 50–90% for read-heavy endpoints, reduce mobile data usage, and lower origin load during cache revalidation storms.

Dica de memória

Conditional GET is like calling a friend to ask 'anything new?' — if nothing changed, they just say 'nope' instead of repeating the whole story.

Upgrade path

stale-while-revalidate and ETag-based optimistic concurrency control

Frequência: MediumFormulaicidade: Semi-fixedPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

import requests url = "https://api.example.com/v1/products/42" headers = {"If-None-Match": '"abc123"'} response = requests.get(url, headers=headers) if response.status_code == 304: print("cached product is still fresh") else: print(response.json())

// Node.js server-side handler app.get('/articles/:id', (req, res) => { const article = db.articles.get(req.params.id); res.setHeader('ETag', article.etag); res.setHeader('Cache-Control', 'private, must-revalidate'); if (req.headers['if-none-match'] === article.etag) { return res.status(304).end(); } res.json(article.body); });

# Go client using net/http with stored Last-Modified req, _ := http.NewRequest("GET", "https://cdn.example.com/app.js", nil) req.Header.Set("If-Modified-Since", storedLastModified) resp, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer resp.Body.Close() if resp.StatusCode == http.StatusNotModified { fmt.Println("using cached bundle") return } body, _ := io.ReadAll(resp.Body) fmt.Println("downloaded", len(body), "bytes")