REST API design review

Review an API design for consistency, evolvability, error handling and security before you ship it.

Change note: Initial version

Prompt

Review the design of this {{style}} API as an experienced API architect.

Purpose and consumers: {{consumers}}
Priorities: {{priorities}}

API description (endpoints, schemas, OpenAPI, or examples):
{{api}}

Assess each area and give concrete findings, not generalities:
1. Resource and naming consistency: URLs, verbs, pluralization, casing, field names.
2. Request and response shapes: nullability, ID formats, timestamps, money and enums, pagination, filtering and sorting.
3. Errors: status codes, error body structure, whether clients can handle failures programmatically.
4. Idempotency and concurrency: retries, duplicate submissions, optimistic locking.
5. Versioning and evolvability: which likely future changes would be breaking, and how to avoid them.
6. Security and abuse: authentication and authorization per endpoint, rate limits, over-exposed fields, mass assignment.
7. Developer experience: discoverability, documentation gaps, surprising behavior.

Output a table of findings (area, issue, severity: high/medium/low, recommended change with an example request or response), followed by the top five changes to make before launch and anything you could not assess from what I provided.

Variables

• {{style}}API styleselect

  Options: REST, GraphQL, gRPC, Webhooks

  Default: REST

• {{consumers}}Purpose and consumerstext

  Default: Public API for third-party developers to manage invoices

• {{priorities}}Prioritiestext

  Default: Stability, easy integration, safe retries

• {{api}}API descriptionlongrequired

  Paste endpoints, an OpenAPI snippet or sample requests.

Example output

| Area | Issue | Severity | Recommendation |
|---|---|---|---|
| Naming | `GET /getInvoices` and `POST /invoice/create` mix verbs and singular/plural | Medium | `GET /invoices`, `POST /invoices` |
| Errors | Failures return 200 with `{"ok": false}` | High | Use 4xx/5xx plus `{"error": {"code": "invoice_not_found", "message": "No invoice with id inv_123", "request_id": "req_8f2a"}}` |
| Idempotency | `POST /invoices` has no retry protection | High | Accept an `Idempotency-Key` header and store the result for 24 h |
| Pagination | `GET /invoices` returns all invoices | High | Cursor pagination: `?limit=50&after=inv_123`, response includes `next_cursor` |
| Money | `amount: 12.5` as float | High | Integer minor units plus currency: `{"amount": 1250, "currency": "USD"}` |
| Security | `GET /invoices/{id}` has no ownership check mentioned | High | Scope by account and return 404 for other accounts' invoices |
| Concurrency | `PUT /invoices/{id}` overwrites silently | Medium | Return an `ETag`, require `If-Match`, answer 412 on mismatch |
| Evolution | `status` is a free string | Medium | Document it as an open enum clients must tolerate new values for |
| Timestamps | `created: "09/01/2026"` | Low | ISO 8601 UTC: `"created_at": "2026-09-01T10:15:00Z"` |

**Top five before launch:** consistent error format, idempotency keys, integer money, cursor pagination, ownership checks.

**Could not assess:** rate limits, auth scopes and webhook signing, since none were described.

Notes

Splitting the review into fixed areas ensures security and evolvability are not skipped. The severity table gives you a ready-made work list.