The request: line, methods, headers, body

The request line

Every HTTP request opens with one line of three whitespace-separated tokens:

GET /catalog/item?id=42 HTTP/1.1

The method says what operation you want. The path — everything after the host name, including the query string — says which resource. The version says which rules you expect the server to follow. That is the entire required content of a request: a server may legally answer a request that is one line long. Everything else is metadata you add because the server needs it.

Note what the path is not: it is not a URL. The scheme and host live in the Host header, not in the request line, so a server reading the line alone cannot tell which of its sites you wanted. That split is why Host became mandatory.

Headers are Keyword: Value

After the request line come header lines, each of the form Keyword: Value. Keywords are case-insensitive — Content-Length, content-length and CONTENT-LENGTH are the same header — but values often are not, so never lowercase a value on the way past. Both keyword and value should be ASCII. A value too long for one line may be continued by starting the next line with a space or a tab, though modern servers dislike it and you should not emit it.

Three headers earn their place in almost every request you will hand-write:

• Host — the server name you meant. Mandatory in HTTP/1.1, because one IP address routinely serves dozens of names (name-based virtual hosting). Omit it and a conforming server answers 400 Bad Request.
• User-Agent — who is asking. Servers use it for statistics and, occasionally, to serve different content.
• Connection — close if you want the server to hang up after answering, which is what you want while debugging by hand.

CRLF, the blank line, and the body

Every line in an HTTP message ends with a carriage-return/linefeed pair, \r\n — two bytes, 13 then 10, not the single \n your text editor writes. The header block ends with an empty line, which on the wire is a second consecutive pair: \r\n\r\n. After that, and only after that, comes the body.

A body is optional and only POST and PUT normally carry one. When you send one, two headers become obligatory: Content-Length, the exact number of body bytes, and Content-Type, their MIME media type. Get the length wrong and the server either truncates your data or waits for bytes that never come.

Methods and their contracts

Four methods carry the load. GET retrieves a representation and is safe — it has no side effects, so a browser or crawler may issue it unasked. PUT stores a representation at a known URL. DELETE removes one. POST uploads a representation and lets the server decide what it means; it is the method for actions that commit. Three more appear in practice: HEAD is a GET with the body suppressed, used to check a size or a date cheaply; OPTIONS asks what a resource permits; TRACE echoes the request back for debugging.

Two properties decide whether a client may repeat a request. Safe means no side effects. Idempotent means doing it twice leaves the server exactly as doing it once did. PUT and DELETE are not safe but are idempotent, so a client whose socket died mid-request may simply send it again. POST is neither, which is why your browser asks before re-submitting a form.

Worked example — a form POST, byte-counted

POST /register HTTP/1.1
Host: www.example.org
Content-Type: application/x-www-form-urlencoded
Content-Length: 31

user=ada+lovelace&list=announce

Count the body: user= is 5, ada 8, + 9, lovelace 17, & 18, list 22, = 23, announce 31. There is no trailing newline — a body is exactly the bytes you declared, and an extra \n would make it 32 and leave the server one byte short, blocking on a read that never completes. The application/x-www-form-urlencoded type is only a convention for browser forms; the same request could send image/jpeg or application/atom+xml and change nothing else about the shape.