REST API Design Principles

The Six REST Constraints

• Client-Server: Separate concerns — clients handle UI, servers handle data storage. They evolve independently.
• Stateless: Each request contains all information needed to process it. No server-side session state between requests.
• Cacheable: Responses must declare themselves cacheable or non-cacheable. Clients and intermediaries can cache appropriately.
• Uniform Interface: A consistent way to interact with resources (the most important constraint — covered below).
• Layered System: Clients can't tell if they're connected directly to the server or through intermediaries (proxies, load balancers, CDNs).
• Code on Demand (optional): Servers can extend client functionality by sending executable code (e.g., JavaScript).

Hierarchical, Predictable, Consistent

Good REST URLs tell a story about resource relationships:

GET  /users                      # All users
GET  /users/42                   # User 42
GET  /users/42/orders            # All orders for user 42
GET  /users/42/orders/7          # Order 7 for user 42
POST /users/42/orders            # Create new order for user 42

Rules of thumb:

• Use plural nouns: /users not /user
• Use kebab-case: /order-items not /orderItems
• Nest only one level deep — beyond that, use query params or top-level resources
• Never put verbs in URLs: POST /users not POST /createUser

Cursor-Based vs Offset-Based

Offset-based (?page=3&limit=20): Simple but breaks when data changes between pages — items can be skipped or duplicated.

Cursor-based (?after=eyJpZCI6NDJ9&limit=20): Uses an opaque cursor pointing to the last item seen. Stable pagination even when data changes.

// Cursor-based response
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6NjJ9",
    "has_more": true
  }
}

Why cursor wins for large datasets: Offset requires OFFSET 10000 which forces the DB to scan and discard 10,000 rows. Cursor uses an indexed WHERE id > 42 — constant time regardless of page number.

# Filtering
GET /orders?status=shipped&created_after=2024-01-01

# Sorting
GET /users?sort=-created_at,name    # descending created_at, then ascending name

# Field selection (sparse fieldsets)
GET /users/42?fields=id,name,email  # Only return these fields

Self-Documenting APIs

HATEOAS (Hypermedia As The Engine Of Application State) means responses include links to related actions and resources — clients don't need to hardcode URLs.

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "_links": {
    "self": "/users/42",
    "orders": "/users/42/orders",
    "update": { "href": "/users/42", "method": "PATCH" },
    "delete": { "href": "/users/42", "method": "DELETE" }
  }
}

This makes APIs discoverable — a client can navigate from any entry point by following links, much like browsing the web.

Structured, Actionable Errors

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" },
      { "field": "age", "message": "Must be at least 18" }
    ],
    "request_id": "req_abc123",
    "docs": "https://api.example.com/docs/errors#validation_error"
  }
}

Good errors include: machine-readable code, human-readable message, field-level details, request ID for debugging, and a link to documentation.