api-contract-design

API contract design

Parallel lanes fail at the seam: the backend returns {data: {...}}, the frontend was written against {...}, and the tests mock a third shape. Freezing the contract first is what makes wave-style parallel work safe (see graphyloop-waves) — this skill is what "frozen" means in practice.

When to activate

• Wave 0 / contract stage of any feature with a backend and a client.
• Adding an endpoint, or changing one that already has callers.
• A field rename, a nullable-to-required change, an error-shape change.
• "The frontend is broken but the API works" — usually a contract drift.

The contract artifact

A contract is a file in the repo, not a paragraph in chat. One of:

• OpenAPI/JSON Schema (openapi.yaml) — best when clients are generated from it.
• A shared schema module (zod/valibot/pydantic) imported by both handler and client — the type checker becomes the enforcer.
• A typed client + a fixtures file consumed by the tests.

Whichever you pick, it must state per endpoint: method + path · auth + required role/scope · path/query params with types and defaults · request body schema · success status + response schema · every error status with its code · idempotency and rate-limit behavior. Anything not written down is not part of the contract and will be implemented differently by each lane.

Shapes and naming

• One envelope for the whole API, chosen once: either bare resources ({"id": ...}) or wrapped ({"data": ..., "meta": ...}). Mixing them per endpoint is the single most common drift.
• Consistent casing (snake_case or camelCase) across every payload — including nested objects and error fields. Pick one; a mapper at the boundary if the database disagrees.
• Timestamps: ISO 8601 UTC strings (2026-08-16T14:03:00Z). Money: integer minor units or a decimal string plus a currency — never a float. Ids: string in JSON even when numeric in the database.
• Nullable vs absent is a decision, not an accident: prefer explicit null for "known empty", omit only for "not requested" (sparse fieldsets).
• Collections always return an object, never a bare top-level array — you will need to add meta later, and an array cannot grow.
• Enums are closed and documented; clients must tolerate an unknown value without crashing (render a fallback).