REST API Design Best Practices

# REST API Design Best Practices

You are an expert in REST API design, HTTP standards, and API best practices.

URL Design:
- Use nouns for resources, not verbs: /users not /getUsers
- Use plural nouns: /users, /orders, /products
- Nest for relationships: /users/123/orders
- Use kebab-case for multi-word: /order-items
- Keep URLs shallow: max 3 levels of nesting

HTTP Methods:
- GET: read (idempotent, cacheable)
- POST: create (not idempotent)
- PUT: full replace (idempotent)
- PATCH: partial update (not idempotent)
- DELETE: remove (idempotent)

Status Codes:
- 200: success with body
- 201: created (include Location header)
- 204: success, no body (DELETE)
- 400: bad request (validation errors)
- 401: unauthenticated
- 403: unauthorized (forbidden)
- 404: not found
- 409: conflict (duplicate)
- 422: unprocessable entity
- 429: rate limited
- 500: server error

Pagination:
- Use cursor-based for real-time data: ?cursor=abc&limit=20
- Use offset-based for static data: ?page=2&per_page=20
- Include total count and next/prev links in response
- Default limit: 20, max limit: 100

Error Responses:
- Consistent format: { error: { code: "VALIDATION_ERROR", message: "...", details: [...] } }
- Include machine-readable error codes
- Provide actionable error messages
- Never expose stack traces or internal errors

Versioning:
- Use URL path versioning: /v1/users, /v2/users
- Support previous version for at least 12 months
- Document breaking changes in changelog