Budi Santoso

Review a REST API design before any client depends on it

Check a draft API against seven questions (naming, idempotency, pagination, errors, versioning, auth) and get back a revised spec with every change marked.

At a glance

Best for: Backend and full-stack developers about to ship an API that mobile apps or third parties will call and that will be hard to change later.
Tested on: Claude · Opus 5.5
You fill in: consumersspec
You get: Naming and methods. POST /createBooking and POST /bookings/cancel are RPC-style. Use POST /bookings to create. Model cancel as a state change, POST… (full result below)

Prompt

Review this API design before we build it. Once clients ship, mistakes here are expensive to undo.

Who calls it: {{consumers}}

Draft spec:
{{spec}}

Answer each question with a specific finding, or "fine":

1. Naming and methods: is anything an RPC call dressed up as REST? Are the HTTP methods right?

1. Idempotency: if a client retries each write after a timeout, what happens? Where do we need idempotency keys?

1. Lists: pagination, filtering and sorting on every list endpoint.

1. Errors: consistent, machine-readable, correct status codes, nothing internal leaked?

1. Versioning: how is it versioned, and what change would force a v2?

1. Auth: for each endpoint, who can read or modify whose data? Flag anything a partner key shouldn't reach.

1. The one decision here that will be hardest to change after clients ship.

Then give me the revised spec in the same notation I used, with each change marked // CHANGED and a few words on why. Keep anything that's fine as it is.

Fill in

{{consumers}}: Who will call the API and howe.g. React Native app, salon owner dashboard, two booking aggregators via API key
{{spec}}: Your draft endpoints and error format, in whatever notation you usee.g. POST /createBooking, GET /bookings?salonId=, ...

Example input

consumers: Our React Native customer app, the salon owner dashboard (web), and two third-party booking aggregators calling with an API key.
spec:
```
POST /createBooking        body: { salonId, serviceId, staffId, startTime, customerPhone }
GET  /bookings?salonId=    returns all bookings for the salon
POST /bookings/cancel      body: { bookingId }
PUT  /bookings/{id}        body: { startTime }   // reschedule
GET  /slots?salonId=&date= returns free slots
Errors: { "success": false, "message": "..." } with HTTP 200
```

1.6k0

Generated Outputs (1)

3 hours ago

Claude

Opus 5.5

3 hours ago

Generated Output

1. Naming and methods. POST /createBooking and POST /bookings/cancel are RPC-style. Use POST /bookings to create. Model cancel as a state change, POST /bookings/{id}/cancel, which is acceptable as an explicit action, or PATCH with status. Reschedule uses PUT with a partial body. PATCH is the honest method.

2. Idempotency. This is the big one. A mobile client on a flaky 4G connection times out on POST /createBooking, retries, and the customer gets two bookings. Require an Idempotency-Key header on create and cancel, and store the key with the response for 24 hours. Cancel should also be naturally idempotent: cancelling an already-cancelled booking returns 200 with the same body.

3. Lists. GET /bookings returning all bookings will get slower every month. Add cursor pagination, a date range filter and a status filter. /slots is bounded by date, so it's fine.

4. Errors. HTTP 200 on failure breaks every HTTP client's retry and monitoring logic. Use real status codes, and a stable machine-readable code, for example 409 slot_unavailable, so the app can show "that slot was just taken" without parsing English.

5. Versioning. There isn't any. Prefix with /v1 now. Changing the startTime format or making a field required would force a v2.

6. Auth. Not specified. A partner API key must only see bookings it created. As drafted, GET /bookings?salonId= would expose every customer's phone number to both aggregators. Salon owners see their salon's bookings, and customers see their own.

7. Hardest to change later: the startTime format. Decide now: ISO 8601 with offset (2026-10-02T15:30:00+05:30). Local times without an offset will cause bugs in partner integrations.

Revised spec
`
POST /v1/bookings // CHANGED: resource-style; requires Idempotency-Key
body: { salonId, serviceId, staffId, startTime, customerPhone } // startTime ISO 8601 with offset
GET /v1/bookings?salonId=&from=&to=&status=&cursor=&limit= // CHANGED: paginated, filtered
// partners: only bookings they created; phone masked
POST /v1/bookings/{id}/cancel // CHANGED: id in path; idempotent
PATCH /v1/bookings/{id} // CHANGED: partial update
body: { startTime }
GET /v1/slots?salonId=&date=&serviceId= // CHANGED: slot length depends on service
Errors: HTTP 4xx/5xx + { "error": { "code": "slot_unavailable", "message": "..." } } // CHANGED
`

Why it works

The seven fixed questions stop the review drifting into style and cover the areas that hurt after launch: retries, unbounded lists, error semantics and data exposure. Asking "what happens if a client retries after a timeout" frames idempotency as a concrete failure (duplicate bookings), not an abstract principle. Question 6, "flag anything a partner key shouldn't reach", caught the phone-number leak. Requiring the revised spec in your own notation with // CHANGED markers gives you something to paste into your design doc, not an essay.

When not to use it

It isn't built for GraphQL schemas, gRPC services or event-driven designs, which have different failure modes, so adapt the questions before you use it. It also can't judge domain rules it doesn't know (can a booking be moved to another staff member?). If partners already integrate with the API, the answer is a migration plan, not a redesign.

Comments (0)

No comments yet. Be the first to share your thoughts!