Best for
- New APIs that should not embarrass you in two years
- Making an organically-grown API consistent
- Teams where every endpoint is a new adventure
What you give it
- What the API must let callers do, and who the callers are
- Your existing conventions, if any endpoint already exists
What you get back
- A written contract: resources, endpoints, request/response shapes, errors
- A consistency review of existing endpoints with specific fixes
- The awkward decisions (versioning, pagination, partial failure) made explicitly
How it works
- Starts from the callers' jobs-to-be-done, not from the database tables.
- Reads existing endpoints first and extends their conventions where they are sound.
- Writes the contract: paths, verbs, shapes, status codes, error envelope, auth.
- Decides the boring hard parts explicitly: versioning, pagination, idempotency, rate limits.
- Walks each caller's journey through the draft to catch missing endpoints and awkward flows.
Example
You: Design the API for our appointment system: book, reschedule, cancel, and a calendar view for staff.
Result: A contract with four resources, uniform error envelopes, idempotent booking via client-generated keys, cursor pagination on the calendar — and a written answer to the double-booking race, not a hope.
Limits — please read
- It designs the contract; implementing it is a separate task.
- It will not break existing callers silently — breaking changes come with a migration story or not at all.
- Domain rules (who may do what) come from you; it asks rather than assumes.