APIs with FastAPI · Chapter 25 of 26
Capstone
By the end of this chapter you have built DakiyaGo's merchant API end to end: bookings priced from the rate card, validated, idempotent and saved in Postgres; tracking that shows each merchant only its own parcels; status changes that only staff can make, sent to merchants as signed webhooks; and tests that catch the bugs that would hurt most. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Production
- 5 tasks
- FastAPI
- In the all labs plan
The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.
Why you need this
Devika has a date: the festive rush opens on the first of November, and the two biggest merchants switch from WhatsApp to the API that morning. Sunita has a condition: "Only my hub staff move a parcel. If a merchant can mark their own parcel delivered, I will hear about it from the customer." Imran has his: "Their developers retry everything. A timeout must never mean two pickups." And Aman has the last word: "It ships with tests, or it does not ship."
Every piece exists already: validation (chapter 3), status codes and errors (4 and 5), dependencies (7), the database and transactions (9 to 11), API keys and permissions (14), background tasks and webhooks (16), tests (21). A product needs them together, in an order that makes sense, with the joins done properly. That is this chapter.
What you build: 5 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
dakiyago.py: booking with a quote
Build DakiyaGo's merchant API in dakiyago.py, keeping everything in Postgres at DATABASE_URL (make your tables when the app starts) and reading STAFF_KEY and WEBHOOK_SECRET from the environment. POST /v1/parcels books a parcel for the merchant whose X-Api-Key is in /workspace/data/merchants.json (no key or an unknown key: 401). The body is to_pincode (six digits), weight_grams (more than 0, at most 30000) and cod_amount (0 or more, default 0); a pincode that is unknown or not active, or cash on delivery where its cod is false, is 422.
It answers 201 with exactly awb (DKG and a number, never repeated), merchant_id, to_pincode, weight_grams, cod_amount, price and status (booked). price is the zone's first slab, plus each further 500 g or part of it at the zone's extra rate, plus for cash on delivery the fee: 2% of the amount rounded up to whole rupees, at least 30. The check restarts your app on the same database and finds the parcels.
- Task 2
dakiyago.py: idempotent bookings
A booking may carry an Idempotency-Key header. The same merchant sending the same booking with the same key again gets the first booking back (201, the same body) and no new parcel; the same key with a different booking is 409; another merchant's identical key is a separate booking; bookings without a key are always new.
The check also runs your app with uvicorn and sends four copies of one booking with one key at the same moment: they must all answer the one parcel.
- Task 3
dakiyago.py: tracking and permissions
GET /v1/parcels/{awb} answers the booking's keys plus events, a list of {"status": ..., "at": ...} oldest first (a new parcel has one, booked, at its booking time). A merchant sees only its own parcels: another merchant's, or an unknown AWB, is 404. Staff (X-Api-Key equal to STAFF_KEY) see every parcel.
POST /v1/parcels/{awb}/events with {"status": ...} is for staff only (a merchant: 403, no key: 401). A parcel moves one step at a time: booked, picked_up, in_transit, out_for_delivery, then delivered or returned; any other move is 409, an unknown status 422, an unknown AWB 404. It answers 200 with the parcel as GET shows it.
- Task 4
dakiyago.py: signed webhooks
PUT /v1/webhook with {"url": ...} (http or https only, else 422; merchants only, staff 403) saves the merchant's webhook URL and answers {"url": ...}. After every status change, POST to that merchant's URL the JSON {"awb": ..., "status": ..., "at": ...} (the new event, at as tracking shows it) with the header X-DakiyaGo-Signature: sha256= and the hex HMAC-SHA256 of the exact body bytes, keyed with WEBHOOK_SECRET.
Send it after the response, so a slow merchant's server never delays the staff member, and never let a failed delivery fail the request. The check runs your app with uvicorn and a merchant's server that takes 2 seconds, then one that is down.
- Task 5
test_dakiyago.py: tests that catch bugs
Write pytest tests for the API, importing app from dakiyago and calling it with a TestClient; read STAFF_KEY from the environment. The check runs them with DATABASE_URL, STAFF_KEY and WEBHOOK_SECRET set, against a new database each time: on your API and on another correct DakiyaGo API (both must pass), then on six copies with one careless change each, each of which must make a test fail.
The careless changes: a booking without an API key is accepted; the price leaves out the cash on delivery fee; a pincode DakiyaGo does not serve now is booked; a retry with the same Idempotency-Key books a second parcel; a merchant can track another merchant's parcel; a delivered parcel can go back in transit.
What you will learn
- The order of checks in a request, and why each comes where it does.
- One caller dependency that every permission builds on.
- Idempotency in the database, so that racing retries make one parcel.
- Webhooks a merchant can trust: signed, sent after the answer, never fatal.
- Tests that catch bugs, not tests that pass.
More in Production
Build "Capstone" yourself
DakiyaGo, a Jaipur courier startup, takes bookings on WhatsApp. Merchants want an API, and you build it. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.