Card 05/ 07
Review Example: Ten Problems in One Endpoint
A POST /createOrder endpoint fails ten checks, from its path to its error bodies.
An API design review applies the checklist to one endpoint, comparing it as written and as reviewed. A pull request titled "Add order creation" adds the endpoint below, and the reviewer runs the twelve questions against it. The requests and responses are illustrative.
As writtenten problems
POST /createOrder?userId=5 takes the whole order model as its body, returns 200 with the stored record including internalNotes, and on failure returns 200 with {"error": "failed"}. A retry after a timeout creates a second order. GET /getOrders?userId=5 returns every order at once, and there is no contract.
As reviewedpasses the checklist
POST /v1/orders takes the customer from the token and accepts only items and deliveryAddress. It returns 201 with Location and a designed response, honours Idempotency-Key, and reports failures as problem details with 4xx or 5xx codes. GET /v1/orders is paginated, and both are in the OpenAPI document with examples.
| Problem | Evidence | Fix |
|---|---|---|
| A verb in the path | /createOrder | POST /orders |
| The user from the query | ?userId=5 | The caller from the token |
| Mass assignment | The whole model accepted | An allow-list of fields |
| Wrong success code | 200 for a creation | 201 with Location |
| Data exposure | internalNotes returned | A designed response type |
| Errors with 200 | {"error": "failed"} | Problem details with a 4xx or 5xx code |
| Unsafe retries | A second order on retry | Idempotency-Key |
| A verb in the read path | /getOrders | GET /orders |
| Unbounded list | Every order at once | Cursor pagination with a maximum |
| No contract or version | Nothing published | An OpenAPI document, under /v1 |
What the review found. None of the ten would fail the author's tests, which used one user, one request and no retries. Every one would have reached clients, and three of them, the user in the query, the exposed notes and the duplicate orders, are incidents rather than inconveniences.
What made it quick. Each problem matched a question on the checklist and had a known fix. The reviewer did not have to argue from taste.
← → move through sections and cards