HTTP in plain terms

methods, codes, headers, body

What it is

HTTP is the language a client and a server talk in. You don't need all of it, but four things come up constantly: the method, the response code, the headers and the body.

It is also the language debugging happens in: "it returned a 404" or "it's giving a 500" is a precise description of a problem, and from it the AI knows at once where to look.

What it looks like in code

A real exchange — the request and the response in full:

curl -i http://127.0.0.1:8765/subs/7

HTTP/1.1 200 OK
server: uvicorn
content-length: 40
content-type: application/json

{"user_id":7,"cities":["Oslo","Bergen"]}

The first line is the code. Then the headers. A blank line separates them from the body.

Methods

The key property of GET is that it must not change anything. That is not a formality: browsers, search engines and caches repeat GET requests on their own. If a GET creates something, it will be created several times.

Response codes

The first digit says who is at fault:

The six codes you will meet most often:

All of those codes in our example are real:

curl -X POST .../subs/7 -d '{"city":"Tromsø"}'   → 201
curl -X POST .../subs/7 -d '{"city":"Tromsø"}'   → 409  (already subscribed)
curl -X POST .../subs/7 -d '{"city":"X"}'        → 422  (shorter than two characters)

Headers

The service fields of a request and a response. Three are worth knowing:

Authorization is the header secrets travel in. Article 7.8 covers it separately.

The body

The data of the request or the response. Almost always JSON. A GET usually has no body — the parameters go in the address:

/subs?city=Oslo&limit=10

That is the query string: "key = value" pairs after the question mark.

What to tell the AI

The server returns 500 on POST /subs/7 with the body {"city": ""}.
It should return 422. Here is the handler: <code>.
Why isn't the validation firing?

What is the right response code when a user tries to subscribe
to a city they are already subscribed to? Explain the choice.

Write curl commands to check all four cases: success, no such
user, duplicate subscription, malformed data. Printing the
response code.

The last prompt gives you a ready set of checks — exactly what the unhappy cases from article 4.1 require.

What to look for

A 200 on an error. A response of {"error": "not found"} with a 200 breaks every client: they look at the code rather than reading the text.

A 500 on malformed data. It means there is no validation and the server died on an unhandled exception. The right answer is 400 or 422.

A GET that changes something. It will repeat itself, with no user involved.

An error message with too much in it. A traceback in the response body shows the project's structure to anyone who asks. Details go to the log, the client gets a short message.

A code chosen at random. 400 instead of 404, 403 instead of 401 — and the client cannot tell "not signed in" from "signed in but not allowed".

Cheat sheet