API-Design-Reviewer: The Reviewer That Catches the Design Flaws You're About to Ship

The Hook

**TL;DR:** Your API is a contract. Once clients build against it, changing field names, status codes, or pagination behavior is a migration — and migrations have costs you're not charging to your engineering budget. API-Design-Reviewer catches the design debt before it is baked in and before it has external dependents.

The most expensive API mistake isn't the one that breaks your current clients. It's the one that **looks fine now** but will require a versioned migration in six months because you used `GET /users/{id}/orders` instead of `GET /orders?user_id={id}`. One is a nested resource that makes sense. The other is a leaky abstraction that will haunt every client developer who needs orders across multiple users. API-Design-Reviewer looks for exactly those patterns.

The 10-Second Pitch

• **REST correctness audit** — Resource modeling, HTTP method usage, status code hygiene
• **OpenAPI spec validation** — RFC-compliant schema definitions, discriminator usage, example fidelity
• **GraphQL schema review** — N+1 risk detection, resolver complexity analysis, type coherence
• **Backward compatibility analysis** — Flags additive-vs-breaking changes, deprecation hygiene
• **Error contract review** — Consistent error shapes, machine-readable error codes, rate limit headers
• **Changelog generation** — Auto-generates client-facing API changelog from diffs

Setup Directions

Step 1 — Register Your API Spec

api-design-reviewer register \

--spec ./api/openapi.yaml \

--version 2.1.0 \

--endpoint https://api.yourcompany.com

Step 2 — Run a Design Review

Use api-design-reviewer to run a full design review of our order management API spec at ./api/openapi.yaml. Focus on: (1) REST modeling correctness, (2) backward compatibility risks in the new v2 endpoints, (3) error contract consistency, (4) pagination design. Report blockers and warnings separately.

Step 3 — Review the Breaking Changes Report

api-design-reviewer diff \

--spec ./api/openapi.yaml \

--baseline ./api/openapi.v2.0.0.yaml \

--output ./reviews/breaking-changes-v2.1.md

Step 4 — Generate Client-Facing Changelog

api-design-reviewer changelog \

--spec ./api/openapi.yaml \

--since 2.0.0 \

--format markdown \

--output ./CHANGELOG.md

Pros / Cons

Verdict

API Design Reviewer is the reviewer who actually reads the spec before the meeting. Most API reviews focus on implementation quality. This one focuses on design quality — which is where the real technical debt lives. Ship a poorly designed API and you're paying for it for years.

**Rating: Essential for any public or partner-facing API. Highly valuable for internal APIs with multiple consumer teams.**