Backend line
REST basics
Diya asks for one parcel by its slip, and the clerk’s reply says what happened.
Stops explain each step. The film plays the whole ride.
- Asking
- Waiting
- The reply
- Refused
She asks for one parcel
Diya shows a slip for one parcel. Asking twice does not change the shelf.
Next stop: The clerk checks the shelf
All stops
The everyday version
A parcel counter. The slip is the address, the verb is what Diya asks, and the clerk’s reply is the status.
- Diyais the Client
The sender who names a parcel and asks for one thing to happen.
- The counteris the Server
The clerk who reads the verb and writes the reply.
- The shelfis the Store
Where the parcels sit. Only the clerk decides which slip means which slot.
Interview questions
Say the short answer first. Go deeper only if they ask.
What does it mean that a verb can be repeated safely?
The shelf ends the same whether she does it once or many times. The words of the reply may still change.
RFC 9110 calls a method idempotent when the intended effect of identical requests equals one request. GET, HEAD, OPTIONS, TRACE, PUT, and DELETE are idempotent. POST is not. Safe methods (GET, HEAD, OPTIONS, TRACE) do not request a change. A repeat of DELETE can leave the same empty shelf while the status changes. A client should not automatically retry a method that is not idempotent.
“Idempotent means the reply is the same every time.”
When does she hand a parcel in, swap it, or fix the label?
Hand-in when the counter picks the number. A full swap replaces a known slot. A small fix changes part of it.
POST targets a resource that processes the body, including creation of a resource the server identifies. PUT replaces the state at a URI the client already knows, and if that URI had no representation the server must answer 201. A successful replacement must answer 200 or 204. PATCH carries a set of changes. It is not guaranteed idempotent, though one patch document can be written so that it is, and the server must apply the whole set or none of it.
“A full swap and a hand-in are the same request.”
What if she gives no name, or the clerk knows her and still says no?
No name means the clerk asks who she is. Knowing her and saying no is a refusal.
401 means the request was not applied because it lacks valid credentials, and the server must send WWW-Authenticate with at least one challenge. 403 means the server understood the request and refuses it. Valid credentials that are not enough ought to be 403, and a 403 can also be unrelated to credentials. A server may answer 404 instead of 403 when it wants to hide that the resource exists.
“No name and not allowed are the same refusal.”
What makes the counter this kind of counter?
Slips name parcels, verbs say what to do, and each ask stands on its own.
HTTP is stateless: each request is understood on its own, so the counter does not remember Diya from the connection. A resource is anything identified by a URI, and the method carries the intent. Nouns in the path and plural collections are a common convention, not a rule of the spec. Hypermedia, where each reply tells her the next legal asks, is the level almost nobody ships. A body of text over the wire, with no slips and no verbs, is not this counter.
“Any reply with a written note is this kind of counter.”
The label is nonsense, but the parcel is wrapped properly. What does the clerk say?
A broken wrap is one answer. A proper wrap with a nonsense label is another. FastAPI uses the second for invalid input.
400 means the server will not process the request because it looks like a client mistake, such as malformed syntax. 422 Unprocessable Content means the content type is understood and the syntax is valid, but the instructions cannot be carried out. RFC 5789 uses 400 for a malformed patch document and 422 when the patch is understood but cannot be applied. FastAPI’s handler for RequestValidationError answers 422.
“Always say everything is fine, and hide the problem in a note.”
Cheat-sheet
Commands you will actually type.
curl -i http://localhost:8000/parcels/42Read one parcel and show the status line.
curl -i -X POST http://localhost:8000/parcels -H 'Content-Type: application/json' -d '{"label":"A"}'Hand in a parcel and let the counter pick the number.
curl -i -X PUT http://localhost:8000/parcels/42 -H 'Content-Type: application/json' -d '{"label":"B","note":"n"}'Replace the whole parcel in a known slot.
curl -i -X PATCH http://localhost:8000/parcels/42 -H 'Content-Type: application/json' -d '{"label":"C"}'Change only the label.
curl -i -X DELETE http://localhost:8000/parcels/42Take that slip off the shelf.