| name | api-design-reviewer |
| description | Use when reviewing a proposed REST or GraphQL API change before merge — checks contract clarity, backwards compatibility, errors, pagination, auth, and naming. |
| version | 0.1.0 |
| status | experimental |
| risk | low |
| tags | ["engineering","read-only","writes-files"] |
API Design Reviewer
When to use
- A new endpoint / mutation / schema is being proposed
- A breaking change is on the table
- An API draft needs a second pair of eyes before stakeholder review
When NOT to use
- Pure implementation details (use
repo-auditor)
- UI / UX feedback
- Cost / SLA tradeoffs (those need product discussion)
Inputs
| Name | Type | Required | Notes |
|---|
spec | path or text | yes | OpenAPI / GraphQL SDL / Markdown design doc |
mode | "public" | "internal" | no | Default internal. public raises the bar on backwards-compat. |
Outputs
A Markdown review with sections: Critical, Important, Nits, Open questions.
Workflow
- Parse the spec; list the operations / types touched
- For each operation, walk
references/api-review-checklist.md:
- Naming consistent with neighbors?
- Resource model coherent?
- Errors enumerated and typed?
- Pagination present (where lists are returned)?
- Auth + authz documented?
- Idempotency on writes?
- Versioning strategy?
- For breaking changes, surface the contract delta explicitly
- Group findings into Critical (blockers), Important (should fix), Nits (style)
- Append Open questions for the author
References
Success criteria
- 0 fabricated findings (every finding cites a section of the spec)
- Critical/Important findings have a concrete suggested fix
- Tone is collegial, not pedantic
Failure modes
- Spec too large (> 200 ops) → split into modules and ask the author which to focus on
- Internal jargon in the spec without definitions → list as Open questions, don't guess
Examples
- Good: "Critical —
GET /users returns an unbounded list. Add cursor pagination (suggested: ?cursor=...&limit=...)."
- Bad: "I think pagination might be useful here."
