0
REST/GraphQL API design review against real client use cases
⁂auto-checked, 3 hours oldAauraNovice
The prompt
Review this API design (not the implementation, the shape of the contract) against the client use cases I'll describe. For each use case, trace exactly how a client would call this API to accomplish it, and flag friction:
1. Over-fetching or under-fetching: does a common use case require multiple round trips that could be one, or return way more data than needed.
2. Inconsistent conventions: naming, pagination style, error shape, versioning, compared across the endpoints I've shown, not against some external standard unless I ask.
3. Idempotency and retry safety: which mutating endpoints are safe to retry blindly, and which aren't but should be (missing idempotency keys).
4. Backward compatibility: if this evolves the way I describe in 'planned future changes', will today's design force a breaking change, or does it leave room to grow.
5. Rank findings by how much client-side pain they'd cause, not by aesthetic preference.
Do not suggest switching REST to GraphQL or vice versa unless the use cases genuinely can't be served well by the current style.
API design/schema: api_spec
Client use cases: use_cases
Planned future changes: future_changes
Where it has been run
| Model | Version | People | Broke | Auto | Last |
|---|---|---|---|---|---|
| Claude | Haiku 4.5 | 0 | 0 | 1/1 | 3 hours ago |
Example output
Use case 'show order history with item thumbnails' requires: GET /orders (list), then N calls to GET /items/{id} per order for thumbnail data, that's a classic N+1 over the wire. Highest-pain finding: add an `include=items` query param or embed a thumbnail_url directly in the order list response.
Inconsistency: POST /orders returns 201 with the full object, but POST /refunds returns 200 with just an id, clients have to special-case refund creation to know they need a follow-up GET. Recommend both return 201 with the created resource.
Idempotency gap: POST /refunds has no idempotency key, and your use case describes a mobile client with flaky connectivity, that's a real double-refund risk. Recommend an `Idempotency-Key` header requirement, same pattern Stripe uses, before this ships to production.
Future-change risk: your planned 'multi-currency' change will need an amount object instead of a bare `amount: number`, doing that now as `{ amount: { value, currency } }` avoids a breaking change later, cost is negligible today.
0 comments
Sign in to comment or report what this prompt did for you.
Sign inNo comments yet. Run the prompt and report what you got.