Design a Clean REST API for a New Resource

This prompt designs a full set of REST endpoints for a new resource, returning method, path, request and response shapes, error codes, and idempotency notes for each — and crucially, flagging cases where REST is the wrong fit. Reach for it at the start of building a new resource when you want a conventional, predictable API surface before writing controllers. The instruction to flag awkward cases is what keeps it honest: it'll tell you when an action doesn't map cleanly to CRUD and a different style would serve you better.

What you can expect back

POST /invoices
Auth: Bearer JWT
Body: { customerId: string; lineItems: { description: string; amountCents: number }[]; dueDate: string }
Response 201: { id: string; status: 'draft'; totalCents: number; createdAt: string }
Errors: 400 invalid body, 401 no/expired token, 404 customer not found, 422 empty line items
Idempotency: not idempotent; support an Idempotency-Key header to dedupe retries.

GET /customers/{customerId}/invoices
Response 200: { data: Invoice[]; nextCursor?: string }
Errors: 401, 404

POST /invoices/{id}/pay   <-- REST-awkward
'Mark paid' is an action, not a resource. Modeled as a sub-action endpoint.
Response 200: { id; status: 'paid'; paidAt }
Errors: 401, 404, 409 already paid/voided
Flag: state transitions (pay/void) don't map cleanly to CRUD; consider a status PATCH or an explicit action endpoint — documented here as the latter.

GET /invoices/{id}/pdf
Returns application/pdf; note: binary download, not JSON.

Illustrative example — your results will vary by tool and inputs.

Get sharper results

• 01List your use cases as verbs and watch which ones don't fit CRUD — 'pay,' 'void,' 'send,' and 'export' are the ones that expose where REST gets awkward, and naming them up front gets you better guidance.
• 02Ask it to be explicit about pagination, filtering, and sorting on list endpoints; these are the details that get retrofitted painfully later.
• 03Have it specify which write operations need idempotency keys versus which are naturally idempotent (PUT, DELETE) so retries don't double-charge or double-create.
• 04Request consistent error envelope shapes across all endpoints, not just status codes, so clients can parse failures uniformly.
• 05If several of your actions are non-CRUD, ask whether the resource is better served by RPC-style endpoints or GraphQL before you commit to forcing everything into REST.

Adapt it for your case