REST API Design: Resources, Verbs, Pagination and Errors Reference Guide

### Collection — list + filter + paginate
GET /v1/orders?status=shipped&customer_id=42&sort=-created_at&limit=20

200 OK
Link: ; rel="next"
{
  "data":     [ { "id": 101, "status": "shipped", "total": "120.00" } ],
  "page_info": { "has_next": true, "cursor": "eyJpZCI6MTAwfQ" }
}

### Single resource — create
POST /v1/orders
Idempotency-Key: 4f1f...
Content-Type: application/json

{ "customer_id": 42, "items": [ { "sku": "ABC", "qty": 2 } ] }

201 Created
Location: /v1/orders/101
{ "id": 101, "status": "pending", ... }

### Validation error
422 Unprocessable Entity
Content-Type: application/problem+json
{
  "type":   "https://api.example.com/problems/validation",
  "title":  "Validation failed",
  "status": 422,
  "errors": [ { "field": "items[0].qty", "code": "min", "message": "must be >= 1" } ]
}

### Cursor — preferred for streams + stable order
GET /v1/orders?limit=50&cursor=eyJpZCI6MTAwfQ
{
  "data":      [ ... ],
  "page_info": { "has_next": true, "cursor": "eyJpZCI6MTUwfQ" }
}

### RFC 5988 Link header — discoverable
Link: ; rel="next",
      ; rel="prev"

### Page-number — easy but bad with mutating data
GET /v1/orders?page=3&per_page=20
{ "data": [...], "page": 3, "total": 412, "per_page": 20 }

### Keyset — fastest under load (since_id / before_id)
GET /v1/orders?since_id=1500&limit=50

### Always:
- Cap `limit` server-side  (e.g. 100 hard, 20 default)
- Encode cursors opaquely  (base64(json)) and treat them as forward-compatible
- Document a deterministic sort order (e.g. -id) — pagination breaks without one

### RFC 9457 (Problem Details for HTTP) — the canonical error format
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type":     "https://api.example.com/problems/order-already-shipped",
  "title":    "Order already shipped",
  "status":   409,
  "detail":   "Order 101 was shipped at 2026-05-17T12:00:00Z and can't be cancelled.",
  "instance": "/v1/orders/101/cancel",
  "trace_id": "abc123",
  "errors":   []
}

### Common shapes
- type     — stable URI per error class
- title    — short human-readable summary (same per type)
- status   — repeat of HTTP status (helps proxies / logs)
- detail   — human-readable, specific to this instance
- instance — URI of the failing request
- errors   — array for field-level validation faults

### URL versioning — most common, easiest to debug
GET /v1/orders/101
GET /v2/orders/101

### Header / media-type versioning — keeps URLs stable
GET /orders/101
Accept: application/vnd.example.api+json;version=2

### Query versioning — fine for internal APIs, weak for caching
GET /orders/101?api_version=2

### Date-based versioning (Stripe-style)
GET /orders/101
Stripe-Version: 2025-05-17

### Rules of thumb
- Adding fields is non-breaking. Removing or changing types is breaking.
- Bumping versions costs the team weeks; do it for shape changes, not field renames.
- Deprecation: announce, ship the new version, keep the old for 6-12 months,
  serve `Deprecation: true` + `Sunset: ` headers, then remove.

### A minimal but production-shaped order resource

# List with filters + pagination
GET /v1/orders?status=shipped&limit=20
Authorization: Bearer ...
200 OK
ETag: "abc123"
Cache-Control: private, max-age=15

# Create with idempotency
POST /v1/orders
Authorization: Bearer ...
Idempotency-Key: 8f3a-...
Content-Type: application/json
{ "customer_id": 42, "items": [...] }
201 Created
Location: /v1/orders/101
{ "id": 101, "status": "pending", ... }

# Read with conditional GET
GET /v1/orders/101
If-None-Match: "abc123"
304 Not Modified

# Partial update
PATCH /v1/orders/101
If-Match: "abc123"
Content-Type: application/merge-patch+json
{ "status": "cancelled" }
200 OK
ETag: "def456"

# Domain error
POST /v1/orders/101/cancel
409 Conflict
Content-Type: application/problem+json
{ "type": "...", "title": "Already shipped", "status": 409 }