An API is a promise you cannot easily take back. Once three teams integrate against your shape, your status codes, and your pagination, you own that shape for years. The cheapest place to fix an API is the design doc. The most expensive place is production. This template is the review you run before code exists, so the same contract mistakes stop getting relitigated across teams. Treat it as a design-discipline problem, not a style-guide one.
the Shape You Cannot Take Back
Resources are nouns, plural, and consistent, modeled deliberately rather than leaking table names into the public shape. A versioning strategy is chosen and written down, changes stay additive within a version, and clients ignore unknown fields. A documented compatibility contract states what can and cannot change, so the first breaking change is not an emergency.
What Happens When Things Go Wrong
One error envelope across every endpoint: a stable machine-readable code, a human message, and a trace id, with correct HTTP semantics. Unsafe writes accept an idempotency key and dedupe retries, and updates use optimistic concurrency to prevent lost updates. A double-clicked checkout should not charge twice, and a 500 should never arrive dressed as a 200.
the Contract Under Load
Authorization is checked at the object level, not just the route, so /accounts/123 cannot return anyone’s account. Rate limits are defined per client with documented 429 behavior. Every request carries a correlation id, logs are structured, and the design names what must never be logged, tokens and PII included.
Fill in the API name, owner, reviewers, consuming teams, and the design doc link. Run it in 45 to 60 minutes with the API owner, one reviewer who owns a consuming service, and one who owns platform or security. Design review is a decision, so name who signs off.
Go section by section, from resource modeling to docs and examples. Mark each item pass, or log a finding. The template pairs every standard with the mistake that shows up most in review, so the reviewer is prompted, not relying on memory.
Grade each finding blocker, major, minor, or nit. An API does not ship with an open blocker or major. Minors and nits are tracked or waived. This is what stops “iterate in prod” from swallowing a real contract flaw.
Approve, approve with conditions, revise and re-review, or reject. Open blockers and open majors must both be zero to approve. Reviewer and owner sign the findings log, so the standard is set once and the same argument does not return next quarter.
Code review checks the implementation. Design review checks the promise. By the time code exists, the shape, the status codes, and the versioning strategy are mostly set, and changing them means rework or a breaking change. The design review catches the expensive mistakes while they are still cheap to fix, in the doc.
Fine for your internal prototype. Not fine for a contract other teams and paying customers depend on. Every breaking change after clients integrate costs a coordinated migration you do not control. The review takes an hour. The migration takes a quarter.
Any API that outlives one team’s sprint: public or partner APIs, platform services that many teams consume, and anything an AI agent will call. Those are the surfaces where an ambiguous contract compounds across every consumer that inherits it.
Forty-five to sixty minutes for the eleven sections, with the owner and two reviewers. The findings log and sign-off add a few minutes. It is a fixed, repeatable ritual, not an open-ended debate, which is the point.
Staff and principal engineers who own technical standards across teams, plus tech leads and platform engineers who keep getting pulled into the same API arguments and want to set the standard once.
Drop your details and we'll send API Design Review Template straight to your inbox - no spam, unsubscribe anytime.
Talk through how this applies to your roadmap with our engineering leads - a working session, not a sales pitch.
Download White Paper