Week 16: API Design at Scale — Versioning, Pagination & OpenAPI

1. API Versioning & Deprecation

The moment an API has consumers you don't fully control, a "breaking change" isn't just a code change — it's a change that breaks someone else's running application. FastAPI's APIRouter makes URI versioning straightforward: mount differently-versioned routers under different prefixes, each with its own response models.

# main.py
from routers import tasks_v1, tasks_v2

app.include_router(tasks_v1.router, prefix="/api/v1/tasks", tags=["tasks-v1"])
app.include_router(tasks_v2.router, prefix="/api/v2/tasks", tags=["tasks-v2"])

Both routers can share the same service layer and database models underneath — only the request/response Pydantic models and route handlers need to differ between versions, so v2's new shape doesn't require duplicating business logic.

Whichever strategy you pick, deprecation needs a signal, not a surprise removal. A Deprecation and Sunset HTTP header (RFC 8594) on the old version's responses gives clients a machine-readable warning and a concrete date, well before the endpoint actually disappears:

from fastapi import Response

@router.get("/{task_id}")
def get_task(task_id: int, response: Response) -> TaskResponseV1:
    response.headers["Deprecation"] = "true"
    response.headers["Sunset"] = "Wed, 01 Apr 2026 00:00:00 GMT"
    response.headers["Link"] = '</api/v2/tasks>; rel="successor-version"'
    return to_response_v1(task_service.get_task(task_id))

2. Pagination, Filtering & Sorting

LIMIT/OFFSET pagination is the simplest default and fine for most admin screens and small datasets. Its real weakness at scale: a large OFFSET forces the database to scan and discard every row before it, so deep pages against a large table get progressively slower — and rows inserted or deleted between page requests can shift offsets, silently skipping or duplicating rows.

@router.get("/tasks")
async def list_tasks(
    db: AsyncSession = Depends(get_db),
    limit: int = 20,
    offset: int = 0,
) -> list[TaskResponse]:
    stmt = select(Task).order_by(Task.created_at.desc()).limit(limit).offset(offset)
    result = await db.execute(stmt)
    return [to_response(t) for t in result.scalars().all()]

Cursor-based (keyset) pagination solves both problems by paginating from a stable reference point instead of a row count — "give me the next 20 tasks created before this specific timestamp," not "give me rows 100 through 120":

@router.get("/tasks")
async def list_tasks(
    db: AsyncSession = Depends(get_db),
    cursor: datetime | None = None,
    limit: int = 20,
) -> TaskPage:
    stmt = select(Task).order_by(Task.created_at.desc()).limit(limit)
    if cursor is not None:
        stmt = stmt.where(Task.created_at < cursor)

    result = await db.execute(stmt)
    tasks = result.scalars().all()
    next_cursor = tasks[-1].created_at if tasks else None
    return TaskPage(items=[to_response(t) for t in tasks], next_cursor=next_cursor)

This is why most large-scale public APIs (Stripe, GitHub, Slack) use cursors rather than offsets — the query stays roughly constant-time regardless of how deep into the dataset a client has paginated, and rows inserted during pagination don't shift already-fetched results.

Standardize filtering and sorting the same way across every list endpoint — ?sort=created_at:desc&status=open, applied identically everywhere — rather than each endpoint inventing its own query parameter shape. A consumer who's learned one endpoint's filtering syntax should be able to guess every other endpoint's correctly.

3. OpenAPI Documentation & Rate Limiting

FastAPI generates OpenAPI docs automatically from your route signatures and Pydantic models, but the defaults are bare — no descriptions, no example values, no documented error responses. Customizing them directly in the route decorator produces documentation a consumer can actually rely on:

@router.get(
    "/{task_id}",
    response_model=TaskResponse,
    summary="Fetch a task by ID",
    responses={
        404: {"description": "No task with that ID"},
    },
)
async def get_task(
    task_id: int = Path(..., description="The task's unique ID", examples=[42]),
) -> TaskResponse:
    ...

With this on the classpath, the browsable Swagger UI at /docs (and ReDoc at /redoc) reflects real descriptions, examples, and documented error cases — generated from exactly the same source of truth as the running code, so it can't drift out of sync the way a hand-maintained separate spec can.

Once an API has external, potentially untrusted consumers, rate limiting protects it from a single client — buggy or malicious — consuming a disproportionate share of capacity. slowapi (a FastAPI-friendly port of Flask-Limiter) implements this as a dependency:

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address, storage_uri="redis://localhost:6379")
app.state.limiter = limiter

@router.get("/tasks")
@limiter.limit("100/minute")
async def list_tasks(request: Request, db: AsyncSession = Depends(get_db)):
    ...

4. Hands-on Exercise

5. Knowledge Check

Three quick questions. Expand each to check your answer.