Think Through API & Client Contracts

Overview

Production guidance for API surfaces and their clients. Each reference paper captures the contract work that first drafts skip: request lifecycle and deadlines, validation edge cases, error taxonomies that do not leak internals, stable pagination under concurrent writes, deprecation windows, webhook signature verification, and realtime reconnection semantics.

Core principle: An API is a compatibility promise. Every endpoint, error, cursor, and webhook is a contract with real clients — including old clients you no longer control.

Domain Law

NO API OR CLIENT CONTRACT CHANGE WITHOUT:
1. the minimum required primary paper(s) for the surface selected from the context table;
2. the paper's pre-change questions
   answered, or each open point labeled as an assumption;
3. "Existing-codebase checks" run when changing an existing API;
4. every applicable MUST mapped to a decision, a test, or a documented
   exception — never silently downgraded.