APIs with FastAPI · Chapter 4 of 26

Response models

By the end of this chapter you can say exactly what a route sends back with a response model, keep secrets and internal fields out of every answer, choose a status code on purpose (201 for something created), keep separate models for what comes in and what goes out, work fields out on the model, and leave empty fields out. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: First API
  • 4 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

Imran got a worried message from a merchant's developer: "Your API sent me a rider's phone number. Should I have that?" The route returned the record DakiyaGo keeps, and the record had everything in it. The data you keep and the data you show are not the same: a merchant's API key, a rider's phone, the cash a parcel carries are needed inside DakiyaGo and dangerous outside it. Chapter 3 checked what comes in. This chapter decides what goes out, once, in a place that cannot be forgotten when someone adds a field next month.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    merchants.py: merchants, without their keys

    merchants.json holds each merchant's id, name, city, plan and api_key, the secret its software books with. Make an app with two routes: GET /merchants answers every merchant in the file's order, and GET /merchants/{merchant_id} answers one (404 for an id that is not there). Each merchant is answered with exactly id, name, city and plan.

    The check also reads /openapi.json: each route's documented answer must be the merchant model (a list of them for GET /merchants), so give each route a response model.

  2. Task 2

    create_parcel.py: book a parcel

    Make an app with one route: POST /parcels takes merchant_id (M and two digits), to_pincode (6 digits), weight_grams (1 to 30000) and cod_amount (0 to 50000, 0 when not sent). It keeps the parcels of parcels.json in memory, adds the new one, and answers status 201 with exactly awb, merchant_id, to_pincode, weight_grams, cod_amount and status.

    The server sets awb and status: the AWB is the next number after the highest in the file (DKG10041, then DKG10042), and the status is booked. An awb or a status in the body changes nothing. The OpenAPI document lists 201 for the route.

  3. Task 3

    tracking.py: the public tracking page

    Make an app with one route: GET /track/{awb} answers exactly awb, status, to_city (the city of the parcel's to_pincode in pincodes.json), delivered (true when the status is delivered) and events (the parcel's events from events.json, in order, each with status, at and hub). An event whose hub is null leaves the hub key out. An AWB that is not in parcels.json answers 404.

    Nothing about the merchant, the weight or cash on delivery goes out. The check reads /openapi.json too: delivered must be worked out on the model from status, not filled in by the route.

  4. Task 4 · interview question

    Interview: accounts.py, signing up a merchant

    Make an app over merchants.json with two routes. POST /merchants takes name (1 to 60 characters) and city (1 to 40) and answers 201 with id, name, city, plan and api_key: the id comes after M05 (M06, then M07), the plan is starter, and the key is new and starts with dkg_test_. An id, a plan or an api_key in the body must not be used. GET /merchants/{merchant_id} answers id, name, city and plan, never the key (404 for an id not there).

    The interviewer will ask what goes wrong with one model for input and output, and which field a client could set that it never should.

What you will learn

  • What a route returns goes out, every field of it.
  • response_model: the model every answer passes through, and the docs it writes.
  • Separate input and output models, so a client cannot set what the server decides.
  • Status codes on purpose: status_code=201 for a created thing.
  • Computed fields, and response_model_exclude_none.

More in First API

Build "Response models" 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.