API Design
One envelope, one error shape, and lifecycle transitions that are not disguised as updates.
Overview
This document covers the response envelope and its exceptions, errors that a client can act on rather than merely display, why lifecycle transitions get their own routes, pagination that cannot be abused, and keeping the backend compatible with a frontend that deploys separately.
Why This Exists
An API's real users are the people writing against it, and most of what makes one pleasant is consistency rather than cleverness. Every inconsistency becomes a conditional in someone else's code. The second reason is narrower and more expensive. Where the client and the server are deployed separately, the API is a contract between two versions that are never quite in step, and every shape change is an exercise in not breaking the version already out there.
One envelope, and the routes that must escape it
Errors a client can act on
Lifecycle transitions are not updates
Pagination and query shape
Evolving without breaking the deployed client
Two hand-written mirrors of one contract
Related Principles· 2
Related Documents· 2
Related Templates
Related Case Studies
Referenced By· 7
Version History
- v0.1.0
Initial structure and metadata established.
- v0.2.0
Written from real experience. Covers the envelope and the responses that must escape it, errors carrying codes and field-level detail, lifecycle transitions as their own routes, pagination clamped where it is used, expand and contract for shape changes, and the unsolved problem of two hand-maintained mirrors of one contract.