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.
What happens by default: ship the endpoint, see who complains, iterate. The shape follows whatever the ORM returns today, errors are a bare 500 or a 200 with a false flag in the body, and versioning is “we’ll figure it out when we break something.” Eighteen months later you are staring at a v2 rewrite and four clients you cannot migrate.
What good design review does: review the contract before a line of handler code exists. Deliberate resource model decoupled from storage, one error envelope with typed codes, versioning and deprecation decided on day one, and a machine-readable schema as the source of truth. The result is additive change for years and no forced migration.
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.
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.
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.
Humans, services, and AI agents all read the same API. Agents are the unforgiving ones: they pick the endpoint from its schema, branch on your error codes, and retry aggressively, so a vague field or an error-as-200 does real damage at scale. You do not build a separate agent API. You hold the line on contract discipline and one API serves everyone. Judgment, not access: wiring up an endpoint is easy, and the review that makes it safe to depend on for years is the work.
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.
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.
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.
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.
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.
