An API Design Review Checklist

Twelve questions, each from an earlier topic, that catch most design problems before a client depends on them.

A design review checks a proposed API against the rules of every earlier topic before any client depends on it. A checklist makes the review repeatable: twelve questions, grouped by the decisions they cover, each with what a failing answer looks like. A design that passes all twelve can still be wrong for its domain, but it will not fail in the ways most APIs do.

The twelve review questions, and what a failing answer looks like
Group	Question	A failing answer
Paths	Are paths nouns, plural and consistent?	POST /createOrder, /getUser
Methods	Does each method match its semantics?	POST for a read, GET that changes data
Methods	Are retried writes safe?	POST payment with no Idempotency-Key
Status codes	Does each response use the code that fits?	200 with an error in the body
Errors	Is every error problem details, with a type a client can act on?	Plain strings, or a stack trace
Collections	Is every list paginated, with a maximum page size?	GET /orders returning every order
Caching	Do responses say how long they may be cached, and by whom?	Private data with no Cache-Control
Concurrency	Can two updates overwrite each other?	PUT with no ETag or If-Match
Security	Is every object checked against the caller?	A userId taken from the query
Security	Are input fields and response fields allow-listed?	The stored record bound in and returned whole
Contract	Is there an OpenAPI document with examples?	Behaviour known only from the code
Evolution	Is every change additive, or planned with a version and sunset date?	A renamed field in place

How to use it. Review the contract, not the code, so problems are found before they are built. Ask each question of every operation, and record each failure with the evidence and the fix.

What it does not catch. Whether the resources match how the domain works, whether the names mean what the business means, and whether a task needs too many calls. Those need someone who knows the domain reading the contract against real tasks.

Automate what you can. A linter for OpenAPI documents, such as Spectral, can check paths, methods, error schemas and pagination on every change. People can then spend the review on what a linter cannot judge.

So review every API against the same twelve questions, before a client is built against it.

← → move through sections and cards