rest-api-design

name	rest-api-design
description	Use when: design RESTful HTTP APIs with correct resources, methods, status codes, and pagination.

Goal: HTTP APIs that follow REST conventions consumers expect.

Use for:

• designing resource-oriented HTTP endpoints
• reviewing method, status code, and URL choices
• adding pagination, filtering, and idempotency

Workflow:

1. Model nouns as resources; use HTTP methods for verbs.
2. Use GET (safe), POST (create), PUT/PATCH (update), DELETE.
3. Return correct status codes: 2xx, 4xx for client, 5xx for server.
4. Make PUT and DELETE idempotent; guard POST with idempotency keys.
5. Paginate collections; support filtering and sorting via query params.
6. Document the contract and version breaking changes.

Conventions:

• plural resource nouns: /users, /users/{id}/orders
• 201 + Location on create, 204 on empty success
• consistent error body with code and message
• cursor or page-based pagination, documented

Rules:

• methods match semantics; GET must not mutate
• choose status codes by meaning, not habit
• keep endpoints resource-oriented, not RPC-in-disguise
• never break URLs or shapes without versioning