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. Express's router makes URI versioning straightforward: mount differently-versioned routers under different prefixes, each with its own Zod schemas.

import { tasksRouterV1 } from "./routes/tasks.v1.js";
import { tasksRouterV2 } from "./routes/tasks.v2.js";

app.use("/api/v1/tasks", tasksRouterV1);
app.use("/api/v2/tasks", tasksRouterV2);

Both routers can share the same service layer and Prisma models underneath — only the Zod request/response schemas 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:

router.get("/:id", async (req, res) => {
  res.set("Deprecation", "true");
  res.set("Sunset", "Wed, 01 Apr 2026 00:00:00 GMT");
  res.set("Link", '</api/v2/tasks>; rel="successor-version"');
  res.json(toResponseV1(await taskService.getTask(req.params.id)));
});

2. Pagination, Filtering & Sorting

Prisma's skip/take gives you offset-based pagination almost for free, and it's the right default for most admin screens and small datasets. Its real weakness at scale: a large skip 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 (req, res) => {
  const page = Number(req.query.page ?? 1);
  const pageSize = 20;

  const tasks = await prisma.task.findMany({
    skip: (page - 1) * pageSize,
    take: pageSize,
    orderBy: { createdAt: "desc" },
  });
  res.json(tasks);
});

Cursor-based (keyset) pagination solves both problems by paginating from a stable reference point instead of a row count. Prisma has first-class support for this via cursor:

router.get("/tasks", async (req, res) => {
  const cursor = req.query.cursor as string | undefined;

  const tasks = await prisma.task.findMany({
    take: 20,
    ...(cursor && { skip: 1, cursor: { id: cursor } }),   // skip the cursor row itself
    orderBy: { id: "desc" },
  });

  const nextCursor = tasks.length === 20 ? tasks[tasks.length - 1].id : null;
  res.json({ items: tasks, nextCursor });
});

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=createdAt:desc&status=open, applied identically everywhere — rather than each endpoint inventing its own query parameter shape.

3. OpenAPI Documentation & Rate Limiting

You already validate every request with Zod (Week 3). @asteasolutions/zod-to-openapi extends the same schemas to generate an OpenAPI 3 spec directly from them — one source of truth for both runtime validation and documentation, so they can't drift apart the way a hand-maintained separate spec would.

import { z } from "zod";
import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";

extendZodWithOpenApi(z);

export const TaskResponseSchema = z.object({
  id: z.string().openapi({ example: "task_abc123" }),
  title: z.string().openapi({ example: "Ship the Q3 report" }),
  status: z.enum(["open", "in_progress", "done"]),
}).openapi("Task");

import { OpenApiGeneratorV3 } from "@asteasolutions/zod-to-openapi";
import swaggerUi from "swagger-ui-express";

const generator = new OpenApiGeneratorV3(registry.definitions);
const openApiDocument = generator.generateDocument({
  openapi: "3.0.0",
  info: { title: "Task API", version: "1.0.0" },
});

app.use("/docs", swaggerUi.serve, swaggerUi.setup(openApiDocument));

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. express-rate-limit backed by Redis (already in your stack since Week 11) is the standard fit:

import rateLimit from "express-rate-limit";
import { RedisStore } from "rate-limit-redis";

const limiter = rateLimit({
  windowMs: 60_000,
  limit: 100,
  store: new RedisStore({ sendCommand: (...args) => redis.call(...args) }),
  keyGenerator: (req) => req.headers["x-api-key"] as string,
});

app.use("/api", limiter);

4. Hands-on Exercise

5. Knowledge Check

Three quick questions. Expand each to check your answer.