HTTP fundamentals

HTTP is the ASCII contract every web service speaks. Once you can read a raw request and response, every framework, gateway, and proxy stops feeling magical — they are all just shaping these same six fields.

The big idea

HTTP is a request–response protocol over TCP. The client sends one text-shaped message, the server sends one back, and the conversation is over. Everything else — REST, GraphQL, APIs, browsers — sits on top of this one exchange. Master the anatomy of that exchange (method, path, headers, body, status), and you can debug almost anything on the wire with nothing but curl and your eyes.

Anatomy of a request and response

Both messages share the same skeleton: a start line, zero or more headers, an empty line, and an optional body. The only difference is the start line — clients send a method + path + version, servers send a version + status code + reason phrase.

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi…
Content-Length: 38
 
{"sku": "SKU-42", "quantity": 2}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /orders/9001
Content-Length: 27
 
{"id": 9001, "status": "new"}

Methods: safe, idempotent, neither

Methods describe intent, not implementation. The two properties that matter for design:

Safe

Doesn't change server state. GET, HEAD, OPTIONS.

Idempotent

Calling it N times has the same effect as calling it once. All safe methods, plus PUT and DELETE.

Neither

POST and PATCH — assume the worst, design for retries.

The practical rule: never make a GET mutate data. Browsers, caches, and crawlers all retry safe methods freely. A GET /cart/checkout is how you get charged twice.

Status codes: five families

Memorise the families, not the codes. The first digit tells you the story.

Headers: the metadata layer

Headers carry everything that is about the message but not part of the payload: identity (Authorization, Cookie), content negotiation (Accept, Content-Type), caching (Cache-Control, ETag), and tracing (X-Request-Id). Custom headers used to be X--prefixed; that convention is dead — just use a descriptive name.

curl -i https://api.example.com/users/42 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ey…' \
  -H 'X-Request-Id: a1b2c3'

In practice

Most HTTP bugs reduce to one of four things:

• Wrong method (using POST where PUT would let retries succeed).
• Wrong status code (returning 200 with {"error": …} so clients can't tell success from failure).
• Missing or wrong Content-Type (your JSON body is being parsed as form-encoded).
• Cache headers you didn't think about (mutating data behind a CDN that's caching it).

Reach for curl -i -v before you reach for the debugger.