Lesson 74 taught me Python for ops scripts. Lesson 125 taught me how to design an API. Neither one taught me how to build the server that answers the calls. That is this lesson. FastAPI is the Python framework I reach for when I need an API server fast, and the reason is simple. I write a Python function, I write a model that says what the request looks like, and FastAPI does the rest. It checks the input, it sends back a clear error when the input is wrong, it writes the docs page for me, and it runs on uvicorn, a small fast server. This lesson follows one request through the whole trip. A client sends a new incident ticket. FastAPI checks it, stores it, and answers 201 Created. Then I show the two ways the trip goes wrong. Ten times the traffic shows up at once, and a client sends a ticket the model refuses. I have debugged APIs at 2 AM the same way I debug anything else. One hop at a time, with curl in one hand and the log in the other.
Difficulty: Intermediate · Know this first: Lesson 74, Lesson 125
I start with a curl command and a blank file. Then I add the route, the model, the handler, and the response, until one request travels the whole pipeline. One ticket makes the trip.
When it breaks, I check:
Every hop charges rent in milliseconds. The bar below is a worked example for one ticket, not a measurement from a live system, but the shape is honest: on the clean path, the handler does the real work and the framework costs about 6 ms. On the spike path, the queue and the handler eat the budget. On the invalid path, the trip is the cheapest of all, because validation stops it before the handler runs. Step through the lesson or switch the scenario and watch the bar change.
The budget bar above shows three fixed stories. This simulator lets you write your own. It answers one question: how much traffic can this API take before the answers get late? You set how many requests arrive per second, how big each request body is, and how many uvicorn workers are running. Move a slider and watch the service time, the capacity, the utilisation, and the p95 change. The numbers are a teaching example, not live measurements. The shape is the lesson: capacity is workers times what one worker can do, and once arrivals pass capacity the queue has no ceiling.
How many requests arrive every second. Two hundred is a quiet internal tool. Two thousand is a busy incident system at noon. More arrivals means a fuller queue, and past capacity it means a queue that never drains.
How big each request body is. Eight KB is a small ticket. Five hundred and twelve KB is a ticket with a pasted log attached. Bigger bodies cost more parse and validation time on every single request.
How many worker processes serve requests. One worker handles one request at a time. More workers means more requests at once, and more memory on the box. Workers are the fastest fix for a saturated API.
Try this: (1) Push requests per second to 2,000 at the defaults. Capacity is 5,000 req/s, so utilisation is 40 percent and the verdict stays comfortable. Now drop the workers to 1. Capacity falls to 2,500 req/s, utilisation hits 80 percent, and the verdict flips to tight. Same code, one fewer worker. (2) Set the body size to 512 KB. Service time jumps to 13.00 ms, one worker serves about 77 req/s, and capacity falls to about 154 req/s at 2 workers. At 200 req/s the utilisation hits 130 percent and the verdict flips to saturated. A big body is a slow request. (3) Set the workers to 8 and the body back to 8 KB, with requests at 2,000. Capacity climbs to 20,000 req/s, utilisation falls to 10 percent, and the verdict flips back to comfortable. Workers are the lever. Watch the budget bar above move too, while the normal scenario is selected: the queue wait lands on hop 2 and the handler time lands on hop 6.
Do this now, in your own terminal. You will write one file, start the server, and prove every endpoint with curl. The store is a dict in memory. Restart the server and the tickets are gone. That is fine for a lab. The shape is what matters, and the shape is production shape.
python3 -m venv /tmp/fastapi-lab-venv /tmp/fastapi-lab-venv/bin/pip install fastapi uvicorn
Versions that ran for this lesson: FastAPI 0.165.0, uvicorn 0.54.0, pydantic 2.14.4.
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import Literal
app = FastAPI(title="Ticket API")
class TicketIn(BaseModel):
title: str = Field(min_length=3, max_length=120)
severity: Literal["low", "medium", "high", "critical"]
priority: int = Field(ge=1, le=5)
team: str = "on-call"
class TicketOut(TicketIn):
id: int
status: str = "open"
tickets: dict[int, TicketOut] = {}
next_id = 1
@app.get("/health")
def health():
return {"status": "ok", "tickets": len(tickets)}
@app.get("/tickets", response_model=list[TicketOut])
def list_tickets(severity: str | None = None, status: str | None = None):
out = list(tickets.values())
if severity:
out = [t for t in out if t.severity == severity]
if status:
out = [t for t in out if t.status == status]
return out
@app.get("/tickets/{ticket_id}", response_model=TicketOut)
def get_ticket(ticket_id: int):
if ticket_id not in tickets:
raise HTTPException(status_code=404, detail="ticket not found")
return tickets[ticket_id]
@app.post("/tickets", response_model=TicketOut, status_code=201)
def create_ticket(body: TicketIn):
global next_id
ticket = TicketOut(id=next_id, **body.model_dump())
tickets[next_id] = ticket
next_id += 1
return ticket
/tmp/fastapi-lab-venv/bin/uvicorn main:app --port 8000
Expected output, exactly as it ran for this lesson:
INFO: Started server process [14345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Run each command in a second terminal. Check your output against the real output below.
$ curl -s http://127.0.0.1:8000/health
{"status":"ok","tickets":0}
$ curl -s -X POST http://127.0.0.1:8000/tickets -H 'Content-Type: application/json' -d '{"title":"Disk 92% full on node 3","severity":"high","priority":2}'
{"title":"Disk 92% full on node 3","severity":"high","priority":2,"team":"on-call","id":1,"status":"open"}
The POST answers 201 Created. The response carries the id and the status, which the client never sent. That is the response model doing its job.
$ curl -s -X POST http://127.0.0.1:8000/tickets -H 'Content-Type: application/json' -d '{"title":"x","severity":"urgent","priority":9}'
{"detail":[{"type":"string_too_short","loc":["body","title"],"msg":"String should have at least 3 characters","input":"x","ctx":{"min_length":3}},{"type":"literal_error","loc":["body","severity"],"msg":"Input should be 'low', 'medium', 'high' or 'critical'","input":"urgent","ctx":{"expected":"'low', 'medium', 'high' or 'critical'"}},{"type":"less_than_equal","loc":["body","priority"],"msg":"Input should be less than or equal to 5","input":9,"ctx":{"le":5}}]}
Three failures, one 422. Read the loc field on each error. It says exactly which field failed and why. That list is the whole debugging story.
$ curl -s "http://127.0.0.1:8000/tickets?severity=high"
[{"title":"Disk 92% full on node 3","severity":"high","priority":2,"team":"on-call","id":1,"status":"open"}]
$ curl -s http://127.0.0.1:8000/tickets/1
{"title":"Disk 92% full on node 3","severity":"high","priority":2,"team":"on-call","id":1,"status":"open"}
$ curl -s http://127.0.0.1:8000/tickets/99
{"detail":"ticket not found"}
The list filters by the query parameter. The single read uses the path parameter. Ticket 99 does not exist, so the handler raises a 404 with a plain message.
Open http://127.0.0.1:8000/docs in a browser. FastAPI wrote that page for you from the routes and the models. Every endpoint is listed, every field is typed, and you can try each one from the page. That page is the fastest way to check a route table, and it is the page I open first when a client reports a 404.
Change one thing and run it again. Send a POST with severity "High" instead of "high". It fails with a 422, because the Literal check is case sensitive. Then send GET /tickets/abc. It fails with a 422 too, because the path parameter is typed int. Both failures happen before the handler runs. That is the lesson in two curl commands.
Three questions. No score is saved anywhere — this is just you against the material.
FastAPI is not one thing. It is four levels of the same job, and every team I have worked with sits on one of them. The levels are not about how clever the code is. They are about how much of the API is checked, documented, tested, and run properly. Read them in order. Each level fixes the failure that hurt the most at the level below it.
At the basic level, the API is one file with one or two endpoints. A GET that returns a dict, a POST that takes a dict. No models, no validation, no tests. The server runs with one uvicorn worker on a laptop. curl is the client, and the docs page is the only documentation. It is how every API starts, and it is fine for exactly one job: proving the endpoint can work at all.
Do this: write one file with a GET /health that returns {"status": "ok"}. Start it with uvicorn, curl it, and watch it answer. Then send it a POST with a body it never asked for, and watch it accept the garbage without complaint. That silence is what the next level fixes.
Uses: A demo for one stakeholder. A script that needs an HTTP front door for an afternoon. A first version built to answer one question: does this endpoint do the job at all. I use this level to learn, never to serve real users.
Scale: One endpoint, one worker, one user at a time. It breaks the moment a second person sends a bad body, because nothing checks the input and the handler crashes on whatever it gets.
Failure modes: A client sends a string where the code expects a number, and the handler throws a 500. The server runs on one worker, so a slow request blocks every request behind it. The API changes and nobody notices, because there is no test and no docs to go stale.
Cost: Almost nothing. One file, one process, no dependencies beyond FastAPI itself.
Trade-offs: Fast to start, impossible to trust. You get a working endpoint in an afternoon, and you pay for it the first time a bad body takes the server down.
At the intermediate level, every endpoint has a request model and a response model. Pydantic checks the input before the handler runs, and the response model decides what leaves the server. The routes are grouped, the errors have clear messages, and the docs page is real documentation because it is generated from the models. This is the level this lesson teaches in full. A test posts one good body and one bad body for each endpoint, and both must pass.
Do this now: run the lab in this lesson, then change one rule in TicketIn and watch the 422 change. Make the title minimum 10 characters, post the same ticket from the lab, and read the new error. Then change it back. You just proved the model is the gate, not the handler.
Uses: A small team serving an internal tool. An incident API like the one in this lesson, where a bad ticket is an annoyance, not an outage. Any API where the callers are people you can talk to when something breaks.
Scale: A handful of endpoints, a few workers, hundreds of requests a second. It holds up until the traffic grows past what the workers can serve, because nothing here scales the box.
Failure modes: A model changes and an old client breaks, because nobody versioned the API. One worker saturates at noon and the queue grows, because the worker count was never raised. A 422 storm looks like an outage, because the alert watches 5xx and ignores 4xx.
Cost: A few workers, a test file, and the discipline to keep the models honest. Cheap in money, and the first real cost in process: somebody has to write the tests and keep the docs true.
Trade-offs: You gain validation and real docs, and you pay with care. The models only help if the team updates them when the API changes, and the first time somebody ships a field without a model, the 422s stop meaning anything.
At the advanced level, the API runs on several workers behind a load balancer, and the handler is thin. Shared work moves into dependencies: one function that loads the current user, one that opens a database session, one that checks the rate limit. The in-memory dict becomes a real database. Background tasks send the notifications after the response goes back, so the client never waits for an email. This is the level a production API needs before it serves real users.
Do this: take the lab API and move the store into a dependency that opens a database session. The handler should not know what a database is. It should ask for a session, store the ticket, and return. Then add a second endpoint that reuses the same dependency, and check that both endpoints open and close their sessions the same way.
Uses: A production service where a bad deploy costs real users: ticket intake, status pages, alert routing. A team that ships a new endpoint every week and needs the rollout to be safe without a person watching every step.
Scale: Dozens of endpoints, several workers per box, thousands of requests a second. The database is the next bottleneck, and the rate limit is what keeps one noisy client from eating the whole service.
Failure modes: A dependency opens a database session and never closes it, and the pool runs dry at noon. A background task fails silently, so the ticket is stored and the notification never goes out. The rate limit is per worker instead of shared, so four workers let one client through four times as often.
Cost: More boxes for the workers, a database, a load balancer, and real engineering time to write the dependencies and the background tasks. The cost is visible on the bill, and it is smaller than the cost of one bad rollout.
Trade-offs: You gain scale and safety together, and you pay with moving parts. The dependencies have to be tested like any other code, and a dependency that fails takes every endpoint down with it.
At the master level, the API is a platform, not a service. The routes are versioned, and old versions keep working while new ones ship. The gateway in front handles auth, rate limits, and routing, the same way Lesson 18 taught. Every endpoint has a contract test in CI, so a breaking change fails the build instead of failing a client. The API publishes an OpenAPI spec, and the client teams generate their clients from it, so the docs and the code can never drift apart. Metrics on every endpoint feed the same dashboards the rest of the system uses.
Do this: write the contract test for one endpoint before you change it. Post one good body and one bad body, and assert the exact status codes and the exact fields in the answer. Then make the breaking change you were planning, and watch the test fail. That failure is the platform working. A breaking change that fails in CI is a fix. The same change failing in production is an incident.
Uses: An API that other teams build on, where a breaking change is an outage for someone else. A public API, where the callers are strangers and the docs are the contract.
Scale: Many services, many versions, millions of requests a day. The gateway absorbs the spikes, and the services behind it scale on their own numbers.
Failure modes: A version is retired while one client still uses it, because nobody tracked who calls what. The gateway becomes the bottleneck, because every request passes through it and nobody scaled it. The contract tests pass and the clients still break, because the tests check the shape and the clients depend on the meaning.
Cost: A gateway, a versioning policy, contract tests, and someone who owns the API as a product. The cost is a team, not a bill.
Trade-offs: You gain a contract other teams can build on, and you pay with ownership. An API at this level needs an owner who says no to breaking changes, and that no is the hardest part of the job.
The lab runs one uvicorn worker. One worker handles one request at a time. That is fine on a laptop and it is a queue in production. The first production change is the worker count. Uvicorn takes a workers flag, and Gunicorn manages the workers for you. Four workers on a four-core box is the starting point, not the answer. The answer is the number where the p95 stops climbing and the CPU stops saturating, and you find it by testing, not by guessing.
uvicorn main:app --workers 4 gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app
The two commands do the same job. Gunicorn is the process manager. Uvicorn is the worker. Gunicorn restarts a worker that dies, and it is the one I use when the API has to stay up while I sleep.
The handler in this lesson does two things: it stores a ticket and it returns it. That is the right size. When a handler starts checking auth, opening a database session, and reading a config file, it is doing three jobs, and the fix is a dependency. FastAPI dependencies run before the handler, and they are the place for shared work. One function loads the current user. One opens the database session. One checks the rate limit. The handler stays thin, and every endpoint shares the same checks.
Pydantic checks the shape. It does not check the meaning. A title of 120 characters that is all spaces passes the length rule and is still garbage. A priority of 1 on every ticket passes the range rule and still breaks triage. Shape validation is the first gate, not the only one. Business rules belong in the handler or in a validator on the model, and they are written down, not assumed.
The client waits for the response. The notification does not have to wait with it. FastAPI background tasks run after the response goes back, and that is where the email and the chat message belong. A ticket that takes 12 ms to store should not take 400 ms to answer because the mail server is slow. The response is the contract. The notification is a side effect, and side effects happen after the contract is kept.
At 10x the traffic, the workers scale first and the database second. The in-memory dict in this lesson becomes a real database, and the handler waits on the database instead of the CPU. At 100x, the API gets a gateway in front of it, the same shape from Lesson 18. The gateway handles auth and rate limits, the GET endpoints get a cache, and the write path gets a queue so a burst of tickets is stored fast and processed in order. The models do not change. The shape of the answer does not change. The parts around the API change, and that is the point. FastAPI is the front door. The building behind it is the system.
A client team shipped a change that sent severity as "High" instead of "high". Every create-ticket call started returning 422. The API was up. The health check was green. The tickets simply stopped arriving, and the support queue went quiet in the middle of the day. Quiet is worse than loud. A loud failure pages someone. A quiet one waits until a user asks where their ticket went.
Three things. First, a contract test in CI posts one ticket of each severity, in both cases, and the build fails if any of them is refused. Second, the 422 alert now logs the failing field name, not just the count, so the next 422 storm names its own cause. Third, a rule: validation errors are never treated as an outage until someone has read one response body. The restarts cost fifteen minutes and fixed nothing. The read cost thirty seconds and found everything.
Design a ticket intake API for 10,000 support agents. It takes 5,000 new tickets a minute at peak, stores them, and lets agents list, filter, and read tickets back. A bad ticket must never be stored, and a lost ticket is a lost customer.
Shape first. One TicketIn model with the rules from this lesson, plus a rule the model cannot check: a title that is only spaces is refused by a validator. One TicketOut model that adds the id, the status, and the created time, and leaves out anything internal. Every endpoint gets both models, so the docs page is the contract.
Then the workers. 5,000 tickets a minute is about 84 a second. One worker serves about 800 small requests a second, so two workers cover the peak with room to spare, and I run four so one worker can die without a page. The workers sit behind a load balancer, and the gateway from Lesson 18 handles auth and rate limits before the API ever sees the request.
Then the store. The in-memory dict from this lesson becomes a real database, because 10,000 agents need tickets that survive a restart. The handler writes the ticket and returns the id. The list endpoint filters by severity and status in the database, not in Python, and it paginates: 50 tickets a call, with a cursor, so no list call ever returns the whole table.
Then the failures. A bad body answers 422 and is never stored. A database that is down answers 503, and the client retries with backoff. The 422 rate has an alert that logs the failing field, because the incident in this lesson taught me that a 422 storm is a client change until proven otherwise.
Trade-offs to name. A queue in front of the write path absorbs the peak, but the client waits longer for the id. Strict validation keeps bad tickets out, but it breaks old clients when the rules change, so the API is versioned and old versions keep working. Pagination keeps list calls fast, but the client has to make more calls to see everything.
Saved in this browser, so the Lessons index can show your progress across the course.