Stress-test an API design
Find the holes in the design before anyone writes the code
This is my API design: [paste the design]. Act as a reviewer and attack it: 1) list the 5 points most likely to break during implementation; 2) say which fields are redundant, and which are missing in a way that forces the client into a second request; 3) suggest changes that stay backward compatible; 4) if there is an obviously simpler alternative, say so outright.
How to use
Feed the critique back in and ask it to defend the design. Whichever point it cannot defend is the one to fix first.
Good for
- No external client uses the endpoint yet, or there is exactly one internal caller: the cheapest moment to change it.
- Web and mobile are about to build in parallel and you need the contract frozen first.
Not for
- The endpoint is live with third parties on it: talk compatibility and rollout, because critique is worth less than a migration plan.
- The disagreement is about business meaning (does this field count as a refund?), not the shape: ask product first.
Example
Input
GET /api/v1/orders?user_id=123
200 {"orders":[{"id":1,"status":"paid","items":[{"sku":"A1","qty":2,"price":1990}]}]}
Client: the home screen needs only the order count and the latest 3; the detail screen fetches line items separately.What you get
Flag that embedding full items in the list makes the home screen pull every line item for 3 orders (bigger payload and N+1 at once), that cursor pagination and a total count are missing, and that status as a bare string breaks clients when a new state appears. Suggest a summary list plus `GET /orders/{id}` for detail, keeping the v1 fields so existing calls do not break.Common mistakes
- Showing only the success response, with no error codes, empty list or pagination edges: half the branches that actually break get missed.
- Treating the critique as 'rewrite it': accepting all five points without checking which ones conflict with your business constraints.
Try tweaking it like this
- Add 'assume this endpoint must carry 10x traffic in three years and serve both web and app' and pagination and versioning surface.
- Ask for 'a concrete bad client snippet for each criticism' to filter out abstract architecture lecturing.