Why this prompt works
This api design prompt starts from what users do, not from database tables, which leads to endpoints that match real actions such as cancelling a booking. Asking for example requests and responses makes the design concrete enough for frontend and backend developers to agree on before any code is written.
A single error format, idempotency keys for create requests and clear status codes such as 409 for conflicts are the details that make an API easy to use. The open questions section surfaces product decisions early, when they are cheap to change.
How to use this prompt
- Tap "Copy prompt".
- Replace every part in [square brackets] with your own details.
- Paste it into ChatGPT or Claude and send.
- Ask a follow-up like "make it shorter" or "give me 3 more options" to fine-tune it.
Variations to try
OpenAPI spec from the design
- Type
- Text
- Fill in
- 1 blank
- Copies
- Be the first
Review an existing API
- Type
- Text
- Fill in
- 1 blank
- Copies
- Be the first
GraphQL schema version
- Type
- Text
- Fill in
- 3 blanks
- Copies
- Be the first
Make it your own
- Add "partners will call this API" to get notes on API keys, rate limits and documentation.
- Ask for the endpoints in your framework's routing format, such as Express or FastAPI.
- Add a webhooks section if other systems need to know when something changes.
Common problems and fixes
- Paths use verbs everywhere. Ask for plural noun resources and use actions like /cancel only where a state change is not a simple update.
- Every error returns 500 or 400. Ask for a table that maps each error case to a specific status code.
FAQ
Should I use REST or GraphQL?
REST is simpler for most CRUD apps and public APIs. GraphQL helps when many clients need different shapes of the same data.
How should I version my API?
A version in the path, such as /v1/, is simple and clear. Avoid breaking changes inside a version.