REST API design review

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

LLazyPrompt(@lazyprompt)CodingCritiqueWorks with any model
No ratings yetSign in to rate
Save 0 Fork Report
Prompt template
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.
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.

Why it works

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

Licensed CC0 (public domain) Version 1 · history