The Server Side: Lifecycle, Routes, and Handlers

By the end of this lesson you can describe what a server does between receiving a request and sending a response, and you can match a method and path against a route table while telling an unknown path apart from a wrong method.

Module 7 looked at HTTP as a client: you send a request and interpret what comes back. This is the same conversation from the other side, and it is where the review assistant's results become available to other software rather than only to whoever runs the script.

The stage worth understanding first is routing, because it is the one that decides whether the selected business handler runs. It is also, conveniently, the stage that needs no server to test: matching a method and path against a table is an ordinary function.

A note on scope. Frameworks such as FastAPI or Flask are what you would use on your own machine, and both are excellent. Neither runs here, and neither runs on the platform hosting this course, which is a Cloudflare Worker executing JavaScript rather than Python. So the examples here model the parts in plain Python. What transfers is the set of responsibilities and the boundary discipline. Frameworks can arrange those responsibilities differently.

A simplified lifecycle for this lesson; real frameworks may arrange these responsibilities differently:

1. Receive. The server accepts a connection and parses the method, path, query string, headers, and body.
2. Route. It matches the method and path to a handler. No match means a response without calling the selected business handler.
3. Authenticate and authorise. Who is asking, and are they allowed? Two separate questions, and conflating them is a recurring source of security defects.
4. Validate. Are the inputs well-formed and within bounds? Reject here rather than deeper in.
5. Handle. Run the actual work, which should be the functions you already have.
6. Serialise. Turn the result into a response body, usually JSON, with a status code and headers.
7. Log. Record what happened, with a request identifier, and without recording anything private.

A route table maps a method and path to a handler. Method and path together identify a route: GET /shortlist and POST /shortlist are two different routes that may or may not both exist.

In this lesson’s route table, that produces a distinction worth getting right:

• 404 Not Found means the path is unknown.
• 405 Method Not Allowed means the path exists but not with that method.

Both are failures; they tell a client different things. A 405 says "this resource exists, you asked for the wrong operation", which is actionable. Returning 404 for both hides that.

Path parameters let one route serve many resources: /shortlist/{notice_id}. The value is extracted and handed to the handler, and it is input from outside, so it is validated like any other.

Two design rules that matter more than any framework detail. Keep handlers thin: a handler should validate, call a function you already have and tested, and serialise the result. Separating business logic from request handling lets you test it without constructing a request or framework context. Here we model routing as a pure function, from method and path to a handler or a status, so test that decision directly rather than through a running server.

def list_shortlist(request):
    return 200, {"results": [{"notice_id": "A-1"}], "count": 1}


def shortlist_summary(request):
    return 200, {"count": 1, "total_value": 310000}


ROUTES = {
    ("GET", "/shortlist"): list_shortlist,
    ("GET", "/shortlist/summary"): shortlist_summary,
}


def handle(method, path, request=None):
    """Return (status, body). Pure: no sockets, no framework."""
    handler = ROUTES.get((method, path))
    if handler is not None:
        return handler(request)

    known_methods = {m for (m, p) in ROUTES if p == path}
    if known_methods:
        return 405, {"error": "method_not_allowed", "allowed": sorted(known_methods)}
    return 404, {"error": "not_found"}


print(handle("GET", "/shortlist"))
print(handle("POST", "/shortlist"))
print(handle("GET", "/nope"))

handle models routing and dispatch: it either calls a matching handler or returns an error tuple. It takes a method and a path and returns a status and a body with no network involved. It does not implement authentication, authorisation, request validation, HTTP serialisation, or logging.

The 405 branch puts the registered methods in an allowed body field for this simulation. That field is not an HTTP header. A real HTTP 405 response must include an Allow header listing the supported methods so a client can correct its request.

Each handler returns a status and a body rather than writing a response. That keeps them thin and independently testable, and it is what lets the same functions be wired into a real framework later without changing them.

Predict the three printed lines.

(200, {'results': [{'notice_id': 'A-1'}], 'count': 1})
(405, {'error': 'method_not_allowed', 'allowed': ['GET']})
(404, {'error': 'not_found'})

Remove the known_methods branch, so any unmatched request returns 404. Predict the three lines, then say what a client loses.

An assistant was asked for a handler returning the shortlist for one state. It produced this.

import sqlite3

connection = sqlite3.connect(":memory:")
connection.execute("CREATE TABLE notices (notice_id TEXT PRIMARY KEY, state TEXT, amount INTEGER)")
connection.execute("INSERT INTO notices VALUES ('A-1', 'OR', 310000)")


def shortlist_by_state(request):
    state = request["query"]["state"]
    rows = connection.execute(
        "SELECT notice_id, amount FROM notices WHERE state = '" + state + "'"
    ).fetchall()
    return 200, {"results": rows}


print(shortlist_by_state({"query": {"state": "OR"}}))

def fetch_by_state(connection, state):
    """Ordinary function. Testable with no request and no server."""
    return connection.execute(
        "SELECT notice_id, amount FROM notices WHERE state = ?", (state,)
    ).fetchall()


def shortlist_by_state(request):
    state = request.get("query", {}).get("state")
    if not state:
        return 400, {"error": "missing_parameter", "parameter": "state"}
    return 200, {"results": fetch_by_state(connection, state)}

Write the route matcher. Four requests, and the wrong-method case must be distinguishable from the unknown-path case.

Loading this exercise…

Optional: add a route with a path parameter, GET /shortlist/{notice_id}, and extend the matcher to recognise it. Decide what to return when the identifier does not exist in the data: a 404 naming the resource, or a 200 with an empty result. Then write one sentence justifying the choice. Both are defensible, and knowing why you picked one is what a reviewer will ask.

Sign in to track your progress on this exercise.

1. Name the seven responsibilities in this lesson’s simplified lifecycle order.
2. What is the difference between 404 and 405?
3. Why should a handler be thin?
4. Why is routing worth testing without starting a server?

Sign in to track your progress on this exercise.

This lesson separates seven request-handling responsibilities; routing decides which business handler is selected, 405 is a more useful failure than 404 when the path exists, and a thin handler keeps every interesting behaviour testable. Next: validating what arrives at that boundary, and writing errors that help a caller without helping an attacker.