Skip to main content

Application Engineering · Playbook

API design review guide

The questions we ask in every API design review, so naming, errors and versioning are settled before the first client ships.

E
Emeka Nwosu Sample 8 Oct 2026
Api design REST

Before the review

Share the resource list, three example requests and responses, and the error cases.

In the review

  • Names: plural nouns for collections, no verbs in paths.
  • Errors: one error shape for the whole API, with a stable machine-readable code.
  • Pagination: cursor-based for anything that can grow.
  • Idempotency: Idempotency-Key on every POST that moves money or sends messages.
  • Versioning: additive changes only within a version.

After

Record decisions in the API's changelog; the review isn't done until it's written down.