oxbshw 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
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 /usersreturns an unbounded list. Add cursor pagination (suggested:?cursor=...&limit=...)." - Bad: "I think pagination might be useful here."