Workspace

HTTP semantics: methods, status, headers and caching

3 day streakD

HTTP semantics: methods, status, headers and caching

Before versions and transports, HTTP is a contract: what a method promises, what a status means, and which headers let caches and retries work safely.

BasicsLesson 1 of 618 min

HTTP separates semantics, what a request means, from wire format, how it is encoded. A GET /users/7 means the same thing in HTTP/1.1, HTTP/2 and HTTP/3. Only the bytes differ. This lesson is about the meaning; the next lessons are about the bytes.

Figure 1.1

An HTTP/1.1 exchange, annotated

POST /v1/messages HTTP/1.1 Request line: method, path and protocol version. POST is neither safe nor idempotent, so it must not be retried blindly.

The request line, headers and body of a streaming model call, then the response. HTTP/1.1 is plain text, which is why you can type it by hand. Hover or focus each part for what it does.

Methods carry promises

MethodSafeIdempotentMeaning
GETYesYesRead a resource. Must not change state.
HEADYesYesLike GET, headers only.
PUTNoYesReplace the resource with this body. Repeating it changes nothing further.
DELETENoYesRemove it. Deleting twice leaves it deleted.
POSTNoNoProcess this. Repeating may create two orders or two charges.
PATCHNoNot guaranteedApply a partial change.

Safe means no state change. Idempotent means doing it twice has the same effect as once. These properties decide what can be retried automatically: a client, proxy or browser may resend an idempotent request after a dropped connection, but must not blindly resend a POST. That is why payment APIs accept an Idempotency-Key header: it makes a POST safe to retry.

Status codes by family

RangeMeaningOnes to know
1xxInformational, more is coming101 Switching Protocols (WebSocket), 103 Early Hints
2xxSuccess200 OK, 201 Created, 204 No Content
3xxGo elsewhere or use your cache301/308 permanent, 302/307 temporary, 304 Not Modified
4xxThe request is wrong; do not retry unchanged400, 401, 403, 404, 409 Conflict, 429 Too Many Requests
5xxThe server failed; retry may help500, 502 Bad Gateway, 503 Unavailable, 504 Gateway Timeout

Caching headers

Cache-Control tells caches what they may do: max-age=3600 (fresh for an hour), no-store (never keep), private (only the user's own browser), immutable (never revalidate). Validators let a cache ask “has it changed?” cheaply: the server sends an ETag, the client later sends If-None-Match, and an unchanged resource returns 304 Not Modified with no body.

Worked exampleA conditional request saving a transfer
First response
200 OK, ETag: "v42", 480 KB body
Later request
If-None-Match: "v42"
Resource unchanged
304 Not Modified, empty body, a few hundred bytes of headers

Same round trip, 99.9% fewer bytes. Tool results fetched repeatedly by an agent benefit the same way.

Keep-alive

HTTP/1.0 opened a new TCP connection per request. HTTP/1.1 made connections persistent by default: after a response, the connection stays open for the next request. That avoids repeating the TCP and TLS handshakes and slow start. But one HTTP/1.1 connection carries one request at a time. Browsers open up to six connections per origin to work around this, and that limit returns when we discuss SSE.

Go deeperChunked transfer: streaming in HTTP/1.1

A response usually announces its size with Content-Length. A streaming response does not know its size in advance, so HTTP/1.1 uses Transfer-Encoding: chunked: each chunk is its length in hexadecimal, a line break, the bytes, and another line break. A zero-length chunk ends the body.

chunked-response.txtText
HTTP/1.1 200 OK
Content-Type: text/event-stream
Transfer-Encoding: chunked

19
data: {"delta":"Hello"}\n\n
1a
data: {"delta":" world"}\n\n
0

Chunk boundaries are a transport detail. A proxy may merge or split them, so a client must never treat one chunk as one event. HTTP/2 and HTTP/3 drop chunked encoding entirely; their DATA frames do the same job.

Where you will meet it

Retries in SDKs

Model SDKs retry 408, 429 and 5xx responses with backoff, and only when the request is safe to repeat or carries an idempotency key.

CDN caching

Static assets with content hashes in their names are served with Cache-Control: max-age=31536000, immutable, so browsers never even ask again.

Agent tools

A web-fetch tool that sends If-None-Match for pages it has already read saves both bandwidth and the tokens of re-reading unchanged content.

Words to know

Idempotent
Repeating the operation has the same effect as doing it once.
ETag
An opaque version identifier a server attaches to a response.
Persistent connection
A connection reused for many requests, also called keep-alive.
Chunked encoding
HTTP/1.1's way to stream a body of unknown length.

Check yourself

Answer out loud before you open each one.

What is the difference between safe and idempotent?

Safe means no state change at all. Idempotent means repeating the request has the same effect as doing it once.

Why do payment APIs accept an Idempotency-Key header?

It lets a client safely retry a POST: the server returns the stored result for a repeated key instead of charging twice.

What does a 304 response save?

The body. The client already has the current version, confirmed by its validator.

Try it

Run curl -sI https://example.com and read the caching headers. Then repeat with -H 'If-None-Match: <the etag>' and check for a 304.

A good place to start

Explore a pattern

A little guidance

Start with a pattern, read through a problem, and mark it solved when the idea clicks. Save anything you want to revisit.

New tutorials are added one at a time. Your bookmarks and solved checkmarks stay in this browser.

Explore the roadmap