Get in touch
Glossary

API Design Review

An API Design Review is a structured, multi-stage process for catching API design and implementation issues before they become expensive rework, rather than relying on one large review at the end. Emmanuel Paraskakis's version uses three gates — Design Review, Pre-Implementation, and Pre-Release — each with specific participants and specific questions, delegating anything a linter or automated tool can catch so human reviewers focus only on what automation can't judge.

Why it matters

Most API problems that are expensive to fix are cheap to catch, if you catch them at the right stage. A naming or resource-modeling mistake caught in a design review costs a conversation; the same mistake caught after implementation costs a rewrite, and after release it costs a breaking change for every consumer. Emmanuel’s three-gate structure is built around that cost curve: design-stage review focuses on intent, resource modeling, and naming, before any code exists; pre-implementation confirms automated checks pass and blocking questions are resolved; pre-release verifies contract conformance, documentation quality, and security posture right before anything ships.

The framework also scales review effort to risk. Not every API needs the same scrutiny — an internal API with a single consumer can rely mostly on automated CI checks and peer review, while an externally facing or partner API requires a governance-level review at multiple gates, because the blast radius of getting it wrong is much larger.

How to apply it

  • Design Review gate — triggered when a design is proposed, before any implementation starts. Validate intent, resource model, naming, and workflow coherence. Participants: the API designer, a peer engineer from a consuming team, the PM, and a data modeler if the schema changes.
  • Pre-Implementation gate — triggered once the design is approved, before the sprint begins. Confirm all automated checks pass and any implementation-blocking questions are resolved.
  • Pre-Release gate — triggered once implementation is complete, before deployment. Verify conformance to the agreed contract, documentation quality, and security posture, with a security reviewer required.
  • Tier the review by API type — internal single-consumer APIs can lean on automated checks and peer review alone; externalizable or partner APIs require governance review at every applicable gate.

FAQ

When should an API Design Review happen — before or after implementation?

Both, at different gates — the process is designed to catch different classes of issues at three distinct points: design intent (before code), automated-check readiness (before the sprint), and contract/security conformance (before release).

Does every API need a full three-gate review?

No. The review intensity should scale with the API's risk profile — a single-consumer internal API needs much lighter review than one that's externally facing or shared with partners.

Who needs to be in a design review?

At minimum, the API designer/lead engineer, a peer engineer from a consuming team, and the PM; a data modeler joins if the schema is changing, and a governance lead joins for new externally facing APIs.

What's the difference between a Design Review and API Governance generally?

Governance is the ongoing set of standards and rules; a Design Review is the specific, gated process that enforces those standards against one particular API as it moves through its lifecycle.

What does the Design Review gate catch that a linter can't?

Design intent, resource modeling choices, naming semantics, and whether the overall workflow makes sense end to end — things that require human judgment, not just conformance checking.