# API Design Reviewer

> Use when reviewing a proposed REST or GraphQL API change before merge — checks contract clarity, backwards compatibility, errors, pagination, auth, and naming.

- Skill: `oxbshw/api-design-reviewer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add oxbshw/api-design-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oxbshw/api-design-reviewer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: oxbshw (https://skillmd.com/u/oxbshw)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oxbshw/api-design-reviewer

---


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