api-design-review

Reviewing an API design

An API is a contract you cannot easily take back. Once a client depends on it, every wart is permanent. Review the contract — the shape clients see — before the implementation, because the implementation can change and the contract mostly cannot.

Review against the dimensions below. For a long-form checklist you can walk item by item, ask for @./checklist.md. The dimensions here are the reasoning; the checklist is the enumeration.

1. Resource & operation model

• Do the nouns and verbs match the domain, or do they leak internal structure? Clients should not have to understand your database schema to call the API.
• Is each operation doing one thing? An endpoint that branches on a mode flag into unrelated behaviors is two endpoints wearing a trenchcoat.
• Are names consistent across the surface (createdAt here, created_time there is a bug waiting to confuse)?

2. Idempotency & safety

• Which operations are safe (no side effects) and which are idempotent (repeatable without changing the result beyond the first)? GET must be safe; PUT/DELETE should be idempotent.
• For non-idempotent creates (POST), is there an idempotency key so a client that retries after a timeout does not create duplicates? Networks retry; if the API has no idempotency story, the client's retry is the bug.
• What happens on a partial failure of a multi-step operation? Is there a defined, observable end state, or can the resource be left half-built?

3. Error model

• Is there one consistent error shape across every endpoint (code, message, machine-readable reason, optionally a correlation id)?
• Do status codes mean what they say? 200 with an error body, 404 for authorization failures, or 500 for client mistakes all break clients that reason about codes.
• Are errors actionable? "Invalid request" forces a support ticket; "field email must be a valid address" lets the client self-correct.
• Are error responses documented as part of the contract, not discovered in production?