From Request to Response

"The Web is a distributed hypermedia application. Its most common use is for retrieving and displaying documents, but the architecture must be general enough to support other uses." — Roy T. Fielding, Architectural Styles and the Design of Network-based Software Architectures (2000)

Volume 14 left you fluent in Python. This volume is about the two frameworks that carry most production Python on the web — and it starts, deliberately, with neither of them.

The reason is that Django and FastAPI look nothing alike and do almost the same thing. One gives you a views.py and a URL conf; the other gives you a decorator and a type annotation. Underneath both, the shape is identical: bytes arrive over a socket, something parses them into an object, something chooses a function to call, that function returns an object, and something turns it back into bytes. Every framework decision either sits in that pipeline or configures it.

So this chapter builds the pipeline. By the end you will have parsed a real HTTP request from raw text, produced a valid response, and handled the two details that account for a surprising share of production bugs — that header names are case-insensitive and that some of them may legitimately appear more than once. None of this needs a framework, and knowing it is what makes both frameworks legible rather than magical.

A request is text, and the first line carries the intent

Strip away the tooling and an HTTP request is a byte string with a strict shape.

Four parts, in a fixed order: a start line giving the method, the target and the protocol version; headers, one per line as Name: value; a blank line; and an optional body. The blank line is the only thing separating metadata from payload, which is why \r\n\r\n appears in every HTTP parser ever written.

Content-Length is the detail worth pausing on. HTTP runs over a stream, so the receiver has no way to know where the body ends except by being told — either a byte count up front, or chunked encoding. A mismatch between the declared and actual length is not a warning; it desynchronises the connection, and it is the mechanism behind an entire class of request-smuggling attacks that Volume 13 covers.

Notice what is not here: no notion of a "route", no JSON, no user. Those are all things a framework builds on top.

The target is not a path

The thing after the method looks like a path and is not one.

Three facts that frameworks paper over and interviews probe. The target is a path plus a query string, and splitting on ? yourself is the bug — urlsplit handles fragments, empty queries and edge cases you will not think of. Query values are percent-encoded, so %20 is a space and %2F is a slash that is not a path separator. And a key may appear more than once, which is why parse_qs returns lists.

That last one explains a real difference you will meet in Part IV: Django's request.GET is a QueryDict that returns the last value from [] and all of them from getlist(), while FastAPI decides based on whether you annotated the parameter as str or list[str]. Both are reasonable; neither is "how HTTP works".

Headers are case-insensitive and repeatable

Two properties, both mandated by the spec, both easy to get wrong with a plain dict.

The plain-dict comparison is the point: dict keeps Accept-Language under one exact-cased key and silently loses the first of the two values. Every framework ships a class like the one above because both behaviours are required.

Two details in that output are worth carrying. Parameters live inside a header value — Content-Type: application/json; charset=utf-8 is one header with a media type and a parameter, so naive == comparison against "application/json" fails on a perfectly valid request. And X-Forwarded-For is a list with the client first, appended to by each proxy — which means trusting it blindly lets a caller forge their own IP, a Volume 13 concern that shows up here as a one-line parsing decision.

A response is the same shape, reversed

The response mirrors the request exactly: a status line, headers, a blank line, a body. Content-Length is computed from the encoded bytes, not the string — a distinction that only bites once you send a name with an accent in it, and then bites hard.

The status table is worth memorising as classes rather than codes. The pairs interviewers actually probe: 201 vs 200 (created, with a Location header, versus merely fine), 401 vs 403 (we do not know who you are, versus we do and you still may not), 400 vs 422 (malformed, versus well-formed but semantically wrong — the one FastAPI returns for a failed validation), and 404 vs 403 for a resource that exists but is not yours, where returning 404 deliberately hides its existence.

The five stages, assembled

Here is the whole pipeline, small enough to read at once. Every framework in this volume is an elaboration of it.

Parse, route, call, serialise, respond. That is the entire lifecycle, and it is worth naming the stages because every framework feature attaches to one of them:

The two frameworks differ in how much they do for you at each stage, not in the stages. Django parses the body only when you ask; FastAPI parses and validates it before your function runs. Neither is doing something the other cannot.

Methods mean things, and two of the meanings are load-bearing

Safe means the request does not change server state, so a crawler, a prefetcher or a browser's address bar may issue it freely — which is why "log out" behind a GET link gets users logged out by their antivirus scanner. Idempotent means repeating the request leaves the same end state, which is what lets a client retry after a timeout without asking whether the first attempt landed.

That second property is not academic. Networks drop responses, not just requests, so a client that times out genuinely does not know whether the order was created. Idempotent methods make the retry safe by definition; for POST you need an idempotency key — a client-supplied identifier the server records so a repeat is recognised rather than re-executed. Payment APIs all work this way, and it is a common senior interview question in Part V.

Common Mistakes

1. Splitting the target on ? by hand. urlsplit handles fragments, empty queries and encoding; a manual split fails on the first URL that is not the shape you pictured.
2. Forgetting that query values are percent-encoded. %20 is a space and %2F is a slash that is not a path separator. Decode with parse_qs/unquote, never by hand.
3. Assuming a query key appears once. ?q=a&q=b is legal, which is why parse_qs returns lists and why Django has getlist.
4. Using a plain dict for headers. Names are case-insensitive and some may repeat, so a dict silently drops values and misses lookups.
5. Comparing Content-Type with ==. application/json; charset=utf-8 is a valid JSON content type. Compare the media type before the semicolon.
6. Computing Content-Length from the string. It is a count of bytes; a multi-byte character makes the declared length wrong and desynchronises the connection.
7. Trusting Host or X-Forwarded-For. Both are client-controlled. Host drives absolute URLs (hence ALLOWED_HOSTS), and X-Forwarded-For is appended to by every proxy.
8. Putting a state change behind GET. Safe methods get issued by crawlers, prefetchers and scanners. Anything that changes data needs a non-safe method.
9. Returning 200 for everything. The status class tells a client whether to retry, re-authenticate, fix its payload or page someone. Collapsing it into the body throws that away.
10. Confusing 401 with 403, or 400 with 422. Unauthenticated versus forbidden; malformed versus well-formed but invalid. Clients branch on these.

Interview Corner

Backend interviews open here surprisingly often, because a candidate who can describe the lifecycle precisely will be able to place every later question — and one who cannot will treat the framework as magic.

Summary

• A request is four parts in a fixed order: start line, headers, blank line, optional body. The blank line is the only boundary between metadata and payload.
• Content-Length tells the receiver where the body ends. It counts bytes, not characters, and a mismatch desynchronises the connection rather than merely warning.
• The target is a path plus a query string. Split it with urlsplit, decode with parse_qs, and remember a key may appear more than once — which is why values are lists.
• Headers are case-insensitive and repeatable. A plain dict misses lookups and silently drops values; every framework ships a case-insensitive multi-dict instead.
• A header value can carry parameters. application/json; charset=utf-8 is valid JSON, so compare the media type before the semicolon.
• A response mirrors a request: status line, headers, blank line, body. The status class is what tells a client whether to retry, re-authenticate or fix its payload.
• The lifecycle is five stages — parse, route, call, serialise, respond. Django and FastAPI differ in how much they do at each stage, not in the stages themselves.
• Safe means "changes nothing". Crawlers, prefetchers and scanners issue safe methods freely, which is why a state change behind GET gets triggered by software you never wrote.
• Idempotent means "repeating it lands in the same state". That is what makes a retry after a timeout safe, because a timeout never tells the client what the server did.
• POST needs an idempotency key to be retry-safe. A client-supplied identifier, stored transactionally with the effect, so a repeat returns the original result rather than re-executing.

In the next chapter, WSGI & ASGI, we look at the contract that lets any Python web application run on any Python web server — a callable, two arguments, and a return value — plus the async successor that exists because the original one had no way to express a connection that stays open.