/api-design-reviewer

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

1. Parse the spec; list the operations / types touched 2. 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?

3. For breaking changes, surface the contract delta explicitly 4. Group findings into **Critical** (blockers), **Important** (should fix), **Nits** (style) 5. Append **Open questions** for the author

References

• [`references/api-review-checklist.md`](references/api-review-checklist.md)

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