API Design Reviewer

Review an HTTP/JSON API for the things that make it pleasant, predictable, and safe to evolve. Give actionable feedback grouped by area, with the corrected shape.

Workflow

- [ ] 1. Inventory the resources, endpoints, methods, and payloads
- [ ] 2. Review against the checklist below
- [ ] 3. Report findings by area with severity and a concrete fix
- [ ] 4. Show the corrected request/response where it helps

Review checklist

1. Resources & URLs

• Nouns, not verbs: POST /orders not POST /createOrder. The HTTP method is the verb.
• Plural collection names: /users, /users/{id}, /users/{id}/orders.
• Lowercase, hyphenated paths; no file extensions; no trailing slashes inconsistency.
• Nest only to express ownership, and not more than ~2 levels deep. Prefer /orders?customer_id=42 over /customers/42/orders/7/items/9/....
• Use IDs in the path, filters in the query string.

2. HTTP methods & semantics

• GET (safe, no side effects, cacheable), POST (create / non-idempotent action), PUT (full replace, idempotent), PATCH (partial update), DELETE (idempotent).
• GET must never mutate state. PUT/DELETE must be idempotent (calling twice = calling once). Support an Idempotency-Key header for POST that creates resources.

3. Status codes (use the specific one)

Avoid "200 with { "error": ... }" — let the status code carry the outcome.

4. Errors (consistent, machine-readable)

Adopt one error envelope everywhere. RFC 9457 Problem Details is a good default:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "email must be a valid address",
  "errors": [{ "field": "email", "code": "invalid_format" }]
}

Include a stable machine-readable code, a human detail, and per-field errors for forms. Never leak stack traces, SQL, or internal hostnames.

5. Collections: pagination, filtering, sorting

• Paginate every list endpoint by default; document the cap.
• Prefer cursor pagination (?limit=20&cursor=...) over offset for large/append-heavy data; return the next cursor in the body or a Link header.
• Filtering and sorting via query params: ?status=open&sort=-created_at.
• Return total counts only when cheap; they're often expensive at scale.

6. Payload conventions

• Pick one case style (snake_case or camelCase) and use it everywhere.
• Timestamps in ISO 8601 UTC (2026-05-22T14:30:00Z). Money as integer minor units + currency code, never floats.
• Be liberal in what you accept, conservative in what you return; don't break clients by removing fields — deprecate first.
• Wrap list responses in an object ({ "data": [...], "next_cursor": "..." }) so you can add metadata without breaking clients.

7. Versioning & evolution

• Version from day one: URL (/v1/...) is simplest and most visible; header-based works too.
• Additive changes (new optional field, new endpoint) are non-breaking. Removing/renaming a field or changing a type is breaking — version it.
• Document a deprecation policy and use the Deprecation/Sunset headers.

8. Security & limits

• Authenticate with Authorization: Bearer <token>; never put credentials in the URL.
• Enforce authorization per resource (object-level), not just per route.
• Validate and bound all inputs (string length, array size, numeric ranges).
• Rate-limit and return 429 + Retry-After; expose RateLimit-* headers.
• Use HTTPS only; set sensible CORS; never trust client-supplied IDs for ownership.

Severity guide

• Critical: broken auth/authorization, GET with side effects, no input validation.
• High: wrong/ambiguous status codes, inconsistent errors, no pagination on large lists.
• Medium: verb-in-URL naming, mixed casing, missing versioning strategy.
• Low: naming polish, optional metadata, documentation gaps.

Example finding

Endpoint: POST /getUserOrders returns 200 { "error": "not found" } for unknown users.

Findings:

[High] Verb in URL + wrong method. Use: GET /users/{id}/orders
[High] Wrong status. Unknown user should be 404, not 200-with-error.
[Medium] No pagination on a potentially large collection. Add ?limit & ?cursor.

Corrected:

GET /v1/users/42/orders?limit=20&cursor=eyJpZCI6N30
200 OK
{ "data": [ ... ], "next_cursor": "eyJpZCI6Mjd9" }

# unknown user:
404 Not Found
{ "type": ".../errors/not-found", "title": "User not found", "status": 404 }

Common edge cases

• Bulk operations: define a clear partial-success contract (e.g. 207 Multi-Status or a per-item results array) rather than all-or-nothing ambiguity.
• Long-running actions: return 202 + a status resource to poll, or a webhook.
• Search: complex queries that don't fit a URL can use POST /resource/search; document why it's a POST.
• GraphQL/gRPC: these conventions are REST-specific; note when the API isn't REST.