API Platform & Lifecycle · Governance and Quality
API Design Reviews
Lightweight reviews that catch the expensive mistakes early.
Automate style checks with linting so human reviews focus on what tools can't judge: does the resource model fit the domain and consumer use cases, are security and authorization right (object-level access, scopes), is it evolvable (IDs, enums, pagination), are errors and edge cases covered, does it fit the rest of the platform? Keep reviews lightweight — a PR on the spec with a checklist and an API guild reviewer, completed in days, not weeks.
API design review checklist
[ ] Use cases and consumers listed; examples for each
[ ] Resource model matches domain language; no leaked DB structure
[ ] AuthN scheme + scopes per operation; object-level authorization described
[ ] Pagination, filtering, sorting follow the guide; max page size
[ ] Idempotency for unsafe operations; concurrency (ETag/If-Match) where edits collide
[ ] Errors: problem types documented; 4xx/5xx mapped
[ ] Evolution: additive by default; enums tolerant; deprecation plan for removals
[ ] Non-functional: rate limits, SLOs, payload sizes, caching
Common pitfalls
- Reviews that block for weeks (teams route around them).
- Naming debates instead of security and evolvability.
- Reviewing after implementation when changes are expensive.
Key points
- Automate style; review substance
- Checklist-driven, time-boxed
- Review the spec PR before coding
Further reading: Zalando: API First
Practice questions
What should a human API reviewer focus on if linting covers style?
Answer
Domain fit, security/authorization, evolvability, error and edge-case handling, and consistency with existing platform APIs.
How do you keep design reviews from becoming a bottleneck?
Answer
Time-box them, use checklists, automate style checks, distribute reviewers (API guild), and review early spec drafts rather than finished code.
Open in the app to mark lessons complete, take notes and track your progress.