Routes, path/query parameters, and validation

Path parameters — part of the URI itself

A {"{...}"} segment in a route’s path becomes a function parameter, automatically extracted from the actual URI a request came in on:

from fastapi import FastAPI

app = FastAPI()

@app.get("/agents/{agent_id}")
def get_agent(agent_id: int):
    return {"agent_id": agent_id, "name": "research_agent"}

A request to /agents/42 calls get_agent(agent_id=42) — as an actual int, already converted, not the string "42". This is the same automatic-validation mechanism from the previous concept, now applied to a path segment: the type hint isn’t just documentation here, it’s a real parsing step.

Requesting /agents/not-a-number — something that can’t be parsed as an int — never reaches get_agent at all:

Valid vs. invalid path parameter

click Run to see this pane's output

That second response is automatic — HTTP status 422, a structured error body, and get_agent never actually running. No manual isinstance check, no try/except needed for this case at all.

Query parameters — everything else in the function signature

Any function parameter not named in the path becomes a query parameter instead — read from the URI’s ?key=value portion:

@app.get("/agents")
def list_agents(model: str = None, limit: int = 10):
    return {"model_filter": model, "limit": limit}

Query parameters from the URI

click Run to see this pane's output

That request calls list_agents(model="claude-sonnet", limit=5). A default value (= None, = 10) makes the parameter optional — omitting it from the URI just uses the default, exactly like a regular function’s default argument.

Query() and Path() — validation beyond just the type

A type hint alone only checks shape (is this an int). Query() and Path() add real constraints — a minimum, a maximum, a length limit — directly in the function signature:

from fastapi import FastAPI, Query, Path

app = FastAPI()

@app.get("/agents")
def list_agents(limit: int = Query(default=10, gt=0, le=100)):
    return {"limit": limit}

@app.get("/agents/{agent_id}")
def get_agent(agent_id: int = Path(gt=0)):
    return {"agent_id": agent_id}

Constraints beyond just type

click Run to see this pane's output

Query(default=10, gt=0, le=100) means: default to 10 if omitted, reject anything not strictly greater than 0, reject anything above 100 — limit never even reaching list_agents in the first case above. Path(gt=0) does the same for a path parameter — the second case — refusing an agent_id of 0 or negative, even though it’s already a valid int.

Header() and Cookie() — the same mechanism, different source

Headers are metadata attached to a request or response, separate from the URI and the body — they describe something about the request rather than being part of the resource itself: what format the body is in, an auth token, a request ID for tracing a call through logs. X-Request-Id: abc123 in the demo below is exactly that kind of header — information about this specific call, not data belonging to /whoami the resource.

Cookies are a specific header (Cookie on requests, Set-Cookie on responses) with one particular job: letting the server recognize the same client across multiple separate requests. Recall from REST’s statelessness principle that the server itself remembers nothing between requests — a cookie is how a client carries its own continuity along, sending the same value back on every request so the server can look it up, most commonly for session identification.

Extracting either one works identically to a query or path parameter — a parameter typed with Header() or Cookie() instead of Query()/Path():

from fastapi import Header, Cookie

@app.get("/whoami")
def whoami(x_request_id: str = Header(default=None), session_id: str = Cookie(default=None)):
    return {"request_id": x_request_id, "session_id": session_id}

Reading a header and a cookie

click Run to see this pane's output

FastAPI automatically converts a parameter name like x_request_id to the header name X-Request-Id — headers conventionally use hyphens, Python identifiers can’t, so this conversion happens for you.

The route-ordering gotcha

Routes are matched top to bottom, and the first matching route wins — worth being careful with, since a dynamic path segment matches almost anything:

@app.get("/agents/{agent_id}")
def get_agent(agent_id: str):
    return {"agent_id": agent_id}

@app.get("/agents/me")
def get_current_agent():
    return {"agent_id": "current-user's-agent"}

/agents/{agent_id} defined first — wrong

click Run to see this pane's output

That request matches /agents/{agent_id} first — me is a perfectly valid string for agent_id — so get_current_agent never actually runs; get_agent(agent_id="me") handles it instead. The fix is ordering the more specific, static route before the dynamic one:

@app.get("/agents/me")
def get_current_agent():
    return {"agent_id": "current-user's-agent"}

@app.get("/agents/{agent_id}")
def get_agent(agent_id: str):
    return {"agent_id": agent_id}

/agents/me defined first — fixed

click Run to see this pane's output

Same request, same two routes, just reordered — now the specific route actually gets a chance to match before the dynamic one swallows it. This is the same top-to-bottom, first-match-wins principle from except clause ordering, applied to routes instead of exception types: list the more specific case first, or it never gets a chance to match.

Check your understanding

1/5

In @app.get("/agents/{agent_id}") def get_agent(agent_id: int):, what does the int type hint actually do?