API Design Review

---
name: api-design-review
description: Review an API design or implementation for consistency and usability. Use when asked to design, review, or critique REST/GraphQL endpoints, contracts, or payloads.
---

# API Design Review

An API is a promise that is expensive to break. Review for the consumer, not the implementer.

## Review checklist

**Resource modeling**
- Endpoints are nouns, not verbs: `GET /users/42/orders`, not `/getOrdersForUser`.
- Hierarchy reflects real ownership; avoid nesting deeper than 2 levels.
- Collection vs item is unambiguous and pluralization is consistent.

**Methods & status codes**
- GET is safe and idempotent; PUT/PATCH/DELETE are idempotent; POST is not.
- Status codes mean what they say: 201 on create (with the created resource or Location), 204 on empty success, 400 for client input errors, 401 unauthenticated vs 403 unauthorized, 404 unknown resource, 409 conflict, 422 semantic validation failure, 429 rate limited.
- Never 200-with-error-in-body.

**Consistency with the existing API**
- Read neighboring endpoints first. Match their naming (snake_case vs camelCase), envelope shape, pagination style (cursor vs offset), filtering and sorting conventions, and error format. Consistency beats personal taste.
- Error responses share one shape everywhere: e.g. `{ "error": { "code": "...", "message": "...", "details": ... } }`.

**Compatibility & evolution**
- Is this change breaking? Removed/renamed fields, changed types, tightened validation, changed defaults all break clients. Require versioning or additive-only changes.
- New required fields on existing requests = breaking.
- Pagination on every unbounded list endpoint — no `SELECT *` APIs.

**Details that bite**
- Time is ISO 8601 UTC; money is integer minor units or decimal string, never float.
- IDs are opaque strings; never expose sequential integers if enumeration matters.
- AuthZ is enforced server-side on every endpoint, including "internal" ones.

## Output

Findings grouped as: Breaking risks / Inconsistencies with existing API / Usability issues / Suggestions — each with the endpoint, the problem, and a concrete proposed shape.