REST API Design

# REST API Design

## Resources, not actions
- Good: `POST /orders`, `GET /orders/123`, `PATCH /orders/123`
- Bad: `POST /createOrder`

## HTTP verbs
- GET: safe, idempotent, no body, cacheable
- POST: create, not idempotent
- PUT: full replace, idempotent
- PATCH: partial update
- DELETE: idempotent

## Status codes
- 200 OK, 201 Created (+ Location header), 204 No Content
- 301 Moved, 304 Not Modified
- 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable
- 429 Rate Limited (+ Retry-After)
- 500 Server Error, 503 Unavailable

## Pagination
- Offset: `?page=2&limit=20` -- simple but slow at scale, unstable
- Cursor/keyset: `?cursor=eyJpZCI6MTAwfQ` -- stable + fast

## Filtering / sorting
`GET /users?role=admin&sort=-createdAt`

## Versioning
- URL: `/v1/...` (most common, simple)
- Header: `Accept: application/vnd.api+json; version=1`

## Errors -- consistent shape
```json
{
  "error": {
    "code": "invalid_email",
    "message": "Email is not valid",
    "field": "email"
  }
}
```

## Other
- Use ISO 8601 timestamps in UTC.
- Use plural nouns for collections.
- Don't leak internal IDs unnecessarily; consider opaque IDs.
- Return created/updated resource in response.