REST Principles

REST (Representational State Transfer) is an architectural style defined by Roy Fielding in 2000. It is not a standard or protocol - it is a set of six constraints. APIs that satisfy these constraints are called RESTful.

The 6 Constraints

# 1. Client-Server
# Separation of concerns: client handles UI/UX, server handles data/logic
# They evolve independently - you can rewrite the React frontend
# without touching the API, and vice versa

# 2. Stateless
# Each request must contain ALL information needed to process it
# Server holds NO session state between requests
# Auth must be in every request (Bearer token, not server-side session)
# Benefits: scalability (any server can handle any request),
#           reliability (no session to lose if server restarts)
# Trade-off: larger request payloads, client manages state

# 3. Cacheable
# Responses must label themselves as cacheable or non-cacheable
# Cache-Control: public, max-age=3600
# Cache-Control: no-store
# ETag: "abc123"  (for conditional requests)
# Benefits: performance (reduced latency), scalability (fewer requests)

# 4. Uniform Interface
# The defining REST constraint. Four sub-constraints:
# a) Resource identification in requests (URI identifies the resource)
# b) Resource manipulation through representations (JSON, XML, etc.)
# c) Self-descriptive messages (Content-Type, status codes explain themselves)
# d) HATEOAS - hypermedia as the engine of application state

# 5. Layered System
# Client cannot tell if it's talking directly to the server or a proxy/CDN
# Enables: load balancers, CDNs, API gateways, security layers
# All transparent to the client

# 6. Code on Demand (optional)
# Server can transfer executable code to client (JavaScript)
# The only optional constraint - rarely discussed

Resource-Oriented Design

REST is about resources (nouns), not actions (verbs). URLs identify resources; HTTP methods express what to do with them.

# WRONG: verb-based URLs (RPC-style)
GET  /getUser?id=42
POST /createUser
POST /deleteUser?id=42
GET  /getUserOrders?userId=42

# RIGHT: resource-based URLs (REST-style)
GET    /users/42          # Get user
POST   /users             # Create user
DELETE /users/42          # Delete user
GET    /users/42/orders   # Get orders for user

# Resources are nouns, plural for collections:
# /users          → collection of all users
# /users/42       → specific user with id 42
# /users/42/posts → posts belonging to user 42
# /posts/7        → specific post (can access directly too)

# Representations: the same resource can be represented differently
# Client negotiates via Accept header:
GET /users/42
Accept: application/json
→ {"id": 42, "name": "Jane"}

GET /users/42
Accept: application/xml
→ <user><id>42</id><name>Jane</name></user>

HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) means responses include links to related actions. Clients navigate the API by following links, not by hardcoding URLs. Most real-world REST APIs skip HATEOAS but it is the "true" REST ideal.

// HATEOAS response example
// GET /orders/42
{
  "id": 42,
  "status": "pending",
  "total": 99.99,
  "customer": {
    "id": 7,
    "name": "Jane Doe"
  },
  "_links": {
    "self": { "href": "/orders/42" },
    "customer": { "href": "/users/7" },
    "cancel": { "href": "/orders/42/cancel", "method": "POST" },
    "invoice": { "href": "/orders/42/invoice" },
    "items": { "href": "/orders/42/items" }
  }
}

// Client follows _links.cancel to cancel the order
// Client does not need to know the cancel URL structure
// API can change URLs without breaking clients