# 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.

Source: Level 250 — https://www.level250.com/glossary/api-design-review