APIs with FastAPI · Chapter 22 of 26

OpenAPI and versioning

By the end of this chapter you can treat your OpenAPI document as a contract: describe every field with examples a developer can copy, name operations so a generated client reads well, run two versions of the API side by side, deprecate a field or a route without breaking anyone, and tell a breaking change from a safe one before you ship it. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Production
  • 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 now has eleven merchants on the API, and their developers live in /docs. Two complaints came in this week. One developer generated a Python client from /openapi.json and got a method called request_pickup_pickups_post(). Another copied the example booking from the docs, sent it, and got a 422: the docs showed no example, so he guessed, and guessed weights in kilos.

Then Devika wants the next version: money in paise instead of rupees (floats and rupees do not mix), and a destination with its city. Aman: "Fine, but Gulabi Block Prints' software reads cod_amount today, and their developer is on leave until Diwali. Whatever we change, their integration must keep working." Your API is no longer just code you can change. Other people's code depends on its shape.

What you build: 4 tasks

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

  1. Task 1

    examples.py: a booking body developers can copy

    A merchant's developer copied a guess from /docs and got 422. Make an app with POST /parcels taking a Booking body: to_pincode (exactly six digits, a string), weight_grams (more than 0, at most 30000) and cod_amount (0 or more, default 0). Every field has a description in the OpenAPI document, and the model carries an example of a whole booking that the API accepts.

    The route answers 201 with the booking, a new awb starting DKG and status booked (keep parcels in a dictionary), and its operationId is book_parcel. The check reads /openapi.json, posts every documented example, and tries a short pincode and a weight of 0.

  2. Task 2

    versions.py: /v2 beside /v1

    Make an app that serves a parcel from /workspace/data/parcels.json in two versions, from two routers with the prefixes /v1 and /v2 and the tags v1 and v2. GET /v1/parcels/{awb} answers exactly awb, status, to_pincode, weight_grams and cod_amount, as the file has them. GET /v2/parcels/{awb} answers awb, status, destination ({"pincode": ..., "city": ...}, the city from pincodes.json), weight_grams and cod_paise (the rupees times 100).

    An unknown AWB answers 404 in both versions, and no route is left without a version.

  3. Task 3

    deprecated.py: deprecate without breaking

    Make an app with GET /v1/parcels/{awb} answering v1's five keys (as in task 2) plus cod_paise; its response model marks cod_amount as deprecated in the OpenAPI document, and it still carries the same rupees.

    Keep the old GET /v1/track/{awb} answering {"awb": ..., "status": ...}, marked deprecated in the document, with the headers Deprecation: true and Sunset: Sun, 31 Jan 2027 00:00:00 GMT on every answer. Unknown AWBs answer 404 on both routes.

  4. Task 4 · interview question

    Interview: breaking.py, a change that looks harmless

    Merchants call POST /v1/quote with {"to_pincode": ..., "weight_grams": ...} (some add their own keys, such as merchant_ref) and read back {"zone": ..., "price": ..., "days": ...}: the zone from pincodes.json, price in whole rupees (the zone's first slab, plus each further 500 g or part of it at its extra rate) and days from the rate card. An unknown pincode is 404.

    Add express delivery: an optional service, standard or express (anything else 422), answered back as service; express costs 60 rupees more. Every old request must answer exactly as before. The interviewer will ask: which harmless-looking changes would have broken every merchant at once?

What you will learn

  • The OpenAPI document as a contract: descriptions, examples, status codes.
  • Generated clients, and why operation ids matter.
  • Versions side by side: /v1 and /v2 from routers.
  • Deprecating a field or a route: say so in the document and in headers.
  • Breaking changes that look harmless, and the rule that avoids them.

More in Production

Build "OpenAPI and versioning" 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.