What this prompt does
This prompt asks the AI to design a REST API for a [domain] with the resources you list in [resources], following industry conventions. For each resource it defines URL structure, HTTP methods with correct status codes, request/response JSON schemas, pagination via [pagination_type], filtering and sorting, partial responses, an error format, a versioning strategy, HATEOAS links, and rate-limit headers — then adds an authentication flow using [auth_method], bulk operations, and webhooks, and emits an OpenAPI 3.1 spec.
The structure works because REST has a large body of conventions that are easy to get subtly wrong, and breaking changes later are painful. Listing [resources] lets the model generate consistent URL and method patterns across the whole API. [pagination_type] (cursor versus offset) is a decision that's hard to reverse once clients depend on it, and [auth_method] shapes the security scheme in the spec. Producing an OpenAPI 3.1 document means the design is machine-readable and ready for codegen.
When to use it
- You're starting a new API and want resource naming and status codes right from day one
- You need a consistent pagination, filtering, and sorting convention across
[resources] - You're choosing between cursor and offset pagination via
[pagination_type] - You want an OpenAPI 3.1 baseline before writing endpoint code
- You need a defensible versioning and error-format strategy
- You're defining
[auth_method]and want it reflected in the spec's security schemes
Example output
Expect a per-resource breakdown (URLs, methods, status codes, schemas), a pagination section using [pagination_type], a standardized error envelope, versioning and rate-limit-header conventions, HATEOAS link examples, and finally a generated OpenAPI 3.1 specification you can paste into Swagger UI or feed to a codegen tool. It reads like an API design doc plus a machine-readable contract.
Pro tips
- List
[resources]completely up front; adding them later is when naming inconsistencies creep in - Choose
[pagination_type]deliberately — cursor-based scales better for large or frequently changing datasets, offset is simpler for small ones - Match
[auth_method]to your real needs; OAuth 2.0 with JWT is heavier than API keys but supports third-party access - Use the OpenAPI output as the source of truth and generate SDKs and docs from it, not the other way around
- Ask the model to keep status codes strict; a 200 with an error body inside is the convention that confuses every client
- Treat HATEOAS as optional weight; include it only if your clients will actually follow the links
