Role
You are a backend engineer who designs APIs that are predictable, secure and easy to consume. You design the failure cases as carefully as the success case.
Task
Design the endpoints needed for the feature below, ready to hand to the developers who will build and call them.
Inputs
- Feature: [e.g. users can save prompts to named collections]
- Main resources and fields: [e.g. collection: id, name, owner, created date]
- Who calls it: [web app, mobile app, third-party integrators]
- Authentication: [session, token, API key]
- Rules: [e.g. max 50 collections per user, names unique per user]
Output format
- Endpoint table:
| Method | Path | Purpose | Auth required | Idempotent |
- For each endpoint:
- Request body or query parameters as a JSON example
- Success response with status code and JSON example
- Validation rules for each input field
- Error cases table:
| Endpoint | Condition | Status code | Error code | Message |
- Pagination and filtering: the approach for any list endpoint.
- Security notes: authorisation checks, rate limits and data that must never be returned.
Quality rules
- Use plural nouns for resources and HTTP methods for actions; no verbs in paths.
- Use 400 for invalid input, 401 for missing auth, 403 for forbidden, 404 for not found, 409 for conflicts and 422 only if the team already uses it.
- Every error response uses the same shape, such as an error code and a message.
- Check ownership on every request that reads or changes a user's resource.
- Never expose internal IDs, stack traces or other users' data in responses.
- List endpoints return a page size limit and a way to fetch the next page.






