FastAPI: API design & OpenAPI

Code can be refactored in an afternoon. A public API cannot: other teams, mobile apps already in users’ pockets, and partners’ scripts depend on every field name and status code. Senior engineers therefore spend real effort on the shape of an API: resources and verbs, status codes, partial updates, versioning, and a machine-readable contract that client generators can use. FastAPI writes the OpenAPI document for you, and this part shows how to make that document good.

1. Resources, verbs and status codes

2. A well-described API, run for real

This app shows the design features together: versioned routers, camelCase JSON on the wire with snake_case in Python, PATCH semantics, 201 with Location, a documented error model, examples, deprecation and clean operation ids. It then inspects its own OpenAPI document.

design features, then the generated OpenAPI

from datetime import datetime, timezone
from typing import Annotated, Literal
from fastapi import APIRouter, Body, FastAPI, HTTPException, Response
from fastapi.routing import APIRoute
from fastapi.testclient import TestClient
from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel

class ApiModel(BaseModel):
    """Base for every public model: camelCase on the wire, snake_case in Python."""
    model_config = ConfigDict(alias_generator=to_camel, validate_by_name=True, extra="forbid")

class Problem(ApiModel):                        # the RFC 9457 error shape (lesson 09)
    type: str = "about:blank"
    title: str
    status: int
    detail: str | None = None

class OrderIn(ApiModel):
    customer_email: str
    gift_message: str | None = None
    delivery_slot: Literal["morning", "evening"] = "morning"

class OrderPatch(ApiModel):
    gift_message: str | None = None
    delivery_slot: Literal["morning", "evening"] | None = None

class OrderOut(ApiModel):
    id: int
    customer_email: str
    gift_message: str | None
    delivery_slot: str
    created_at: datetime

NOT_FOUND = {404: {"model": Problem, "description": "No such order (or not yours)"}}
CONFLICT = {409: {"model": Problem, "description": "The order is no longer editable"}}

def operation_id(route: APIRoute) -> str:       # "orders-create" instead of "create_order_v1_orders_post"
    return f"{route.tags[0]}-{route.name}"

app = FastAPI(title="Orders API", version="1.4.0", generate_unique_id_function=operation_id,
              description="Orders for the Brew & Bean shop. All times are UTC.",
              openapi_tags=[{"name": "orders", "description": "Create and manage orders"}])
v1 = APIRouter(prefix="/v1/orders", tags=["orders"])
DB: dict[int, dict] = {}

@v1.post("", status_code=201, summary="Create an order")
def create(body: Annotated[OrderIn, Body(openapi_examples={
        "gift": {"summary": "A gift order", "value": {"customerEmail": "[email protected]",
                                                        "giftMessage": "Happy birthday!"}}})],
           response: Response) -> OrderOut:
    order_id = len(DB) + 1
    DB[order_id] = {"id": order_id, **body.model_dump(), "created_at": datetime(2026, 9, 19, tzinfo=timezone.utc)}
    response.headers["Location"] = f"/v1/orders/{order_id}"
    return DB[order_id]

@v1.get("/{order_id}", responses=NOT_FOUND)
def read(order_id: int) -> OrderOut:
    if order_id not in DB:
        raise HTTPException(404, "no such order")
    return DB[order_id]

@v1.patch("/{order_id}", responses=NOT_FOUND | CONFLICT)
def update(order_id: int, patch: OrderPatch) -> OrderOut:
    changes = patch.model_dump(exclude_unset=True)           # only what the client actually sent
    DB[order_id].update(changes)
    return DB[order_id]

@v1.get("/{order_id}/legacy-status", deprecated=True)
def legacy_status(order_id: int) -> dict:
    return {"status": "paid"}

app.include_router(v1)

with TestClient(app) as client:
    r = client.post("/v1/orders", json={"customerEmail": "[email protected]", "giftMessage": "Happy birthday!"})
    print(r.status_code, "Location:", r.headers["location"])
    print("wire format:", r.json())
    client.patch("/v1/orders/1", json={"deliverySlot": "evening"})     # giftMessage not sent: unchanged
    print("after PATCH:", {k: v for k, v in client.get("/v1/orders/1").json().items() if k != "createdAt"})
    client.patch("/v1/orders/1", json={"giftMessage": None})           # sent as null: cleared
    print("cleared gift:", client.get("/v1/orders/1").json()["giftMessage"])

spec = app.openapi()
print("\noperation ids:", [op["operationId"] for path in spec["paths"].values() for op in path.values()])
post = spec["paths"]["/v1/orders"]["post"]
patch = spec["paths"]["/v1/orders/{order_id}"]["patch"]
print("documented responses: POST", sorted(post["responses"]), " PATCH", sorted(patch["responses"]))
print("PATCH 409 body schema:", patch["responses"]["409"]["content"]["application/json"]["schema"])
print("request example names:", list(post["requestBody"]["content"]["application/json"]["examples"]))
print("OrderOut fields:", list(spec["components"]["schemas"]["OrderOut"]["properties"]))
print("deprecated:", [p for p, ops in spec["paths"].items() if any(o.get("deprecated") for o in ops.values())])

Output

201 Location: /v1/orders/1
wire format: {'id': 1, 'customerEmail': '[email protected]', 'giftMessage': 'Happy birthday!', 'deliverySlot': 'morning', 'createdAt': '2026-09-19T00:00:00Z'}
after PATCH: {'id': 1, 'customerEmail': '[email protected]', 'giftMessage': 'Happy birthday!', 'deliverySlot': 'evening'}
cleared gift: None

operation ids: ['orders-create', 'orders-read', 'orders-update', 'orders-legacy_status']
documented responses: POST ['201', '422']  PATCH ['200', '404', '409', '422']
PATCH 409 body schema: {'$ref': '#/components/schemas/Problem'}
request example names: ['gift']
OrderOut fields: ['id', 'customerEmail', 'giftMessage', 'deliverySlot', 'createdAt']
deprecated: ['/v1/orders/{order_id}/legacy-status']

3. Versioning and evolution

• URL versioning (/v1, /v2) is the most common and the easiest to route, cache and see in logs. Each version is its own APIRouter, sharing services underneath.
• Evolve inside a version with additive changes only. Introduce /v2 only for a real break, and run both in parallel.
• Deprecate loudly: deprecated=True in OpenAPI, plus Deprecation and Sunset response headers (RFC 9745 and RFC 8594), plus monitoring of who still calls the old endpoint before removing it.
• Pin the contract in CI: diff the generated openapi.json against the last release (for example with oasdiff) and fail the build on breaking changes.

4. Docs in production

/docs and /openapi.json describe every endpoint, which helps attackers as much as partners. For internal or partner APIs, either switch them off or put them behind authentication:

docs off by default, served only to admins

from typing import Annotated
from fastapi import Depends, FastAPI, Header, HTTPException
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.testclient import TestClient

app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)       # nothing public

def admin_only(x_api_key: Annotated[str | None, Header()] = None):
    if x_api_key != "admin-key-from-settings":
        raise HTTPException(404)                                     # don't even admit the docs exist

@app.get("/v1/ping")
def ping():
    return {"ok": True}

@app.get("/internal/openapi.json", include_in_schema=False, dependencies=[Depends(admin_only)])
def openapi():
    from fastapi.openapi.utils import get_openapi
    return get_openapi(title="Orders API", version="1.4.0", routes=app.routes)

@app.get("/internal/docs", include_in_schema=False, dependencies=[Depends(admin_only)])
def docs():
    return get_swagger_ui_html(openapi_url="/internal/openapi.json", title="Orders API docs")

with TestClient(app) as c:
    print("/docs              ", c.get("/docs").status_code)
    print("/openapi.json      ", c.get("/openapi.json").status_code)
    print("/internal/docs     ", c.get("/internal/docs").status_code, "(no key)")
    print("/internal/docs     ", c.get("/internal/docs", headers={"X-API-Key": "admin-key-from-settings"}).status_code, "(admin)")
    print("paths in the spec: ", list(c.get("/internal/openapi.json", headers={"X-API-Key": "admin-key-from-settings"}).json()["paths"]))

Output

/docs               404
/openapi.json       404
/internal/docs      404 (no key)
/internal/docs      200 (admin)
paths in the spec:  ['/v1/ping']

5. Details that separate good APIs from great ones

Recap