REST

TL;DR

Designing highly consistent, stateless resource schemas using standardized HTTP methods.

Visual System Topology

REST Network Handshake Flow

Client Node Initiates Request

Multiplexed

REST Gateway Routes Traffic

Fast Payload

Backend Server Executes Logic

Concept Overview

REST (Representational State Transfer) is an architectural style for designing networked applications, defined by Roy Fielding in his 2000 dissertation. RESTful APIs use HTTP as the transport layer and model all interactions as operations on resources (nouns), using standard HTTP methods (verbs) to express the action.

REST is the dominant API design paradigm for public-facing web APIs. It is simple, cacheable, stateless, and universally supported by every HTTP client. The constraints that make REST powerful: statelessness (no client context stored on the server), uniform interface (standard verbs and resource URLs), cacheability (responses declare their cacheability), and layered system (clients cannot tell if they're talking to a load balancer, CDN, or origin).

REST is not a specification but an architectural style. "RESTful" APIs vary widely in practice — many violate REST constraints while calling themselves REST. True REST (HATEOAS-compliant) is rarely implemented in practice; most "REST APIs" are really HTTP/JSON RPC.

Key Architectural Pillars

Resource-Oriented URL Design

Resources are identified by URLs (nouns). Use plural nouns for collections, singular for individual items. Nest resources to express relationships. Avoid verbs in URLs — the HTTP method IS the verb.

Example: GET /users/123/orders/456 — get order 456 for user 123. NOT GET /getOrderForUser?userId=123&orderId=456.

HTTP Methods (CRUD Mapping)

GET: read, idempotent, cacheable. POST: create, non-idempotent. PUT: replace (full update), idempotent. PATCH: partial update. DELETE: remove, idempotent. HEAD: like GET but headers only. OPTIONS: list allowed methods (CORS preflight).

Example: POST /orders → create order. GET /orders/123 → read order. PUT /orders/123 → replace order. PATCH /orders/123 → partial update. DELETE /orders/123 → cancel order.

HTTP Status Codes

2xx success: 200 OK, 201 Created (POST), 204 No Content (DELETE). 3xx redirect: 301 Moved Permanently, 304 Not Modified (cached). 4xx client error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests. 5xx server error: 500 Internal Server Error, 503 Service Unavailable.

Example: POST /users returns 201 with Location: /users/123 header. GET /users/999 returns 404. POST /users with missing required field returns 422 with error details.

Statelessness

Each request must contain all information needed to process it — the server stores no client session state between requests. Enables horizontal scaling (any server can handle any request), simplifies load balancing, and improves reliability (server restarts don't affect clients).

Example: Every API call includes the Authorization: Bearer {token} header. The server validates the token per-request without needing session storage.

Content Negotiation

Client and server negotiate the response format via Accept and Content-Type headers. Same resource URL can return JSON, XML, or other formats depending on what the client accepts.

Example: Client sends Accept: application/json → receives JSON. Accept: application/xml → receives XML. Content-Type: application/json on POST → server expects JSON body.

Versioning Strategies

URI versioning (/v1/users) — most common, immediately visible. Header versioning (Accept: application/vnd.api+json; version=1) — clean URLs but less discoverable. Query param (/users?version=1) — easy but pollutes query string. Stripe uses URI versioning with date-based versions (2024-01-01).

Example: Stripe API: POST /v1/charges with header Stripe-Version: 2024-01-01 for explicit version pinning.

Foundations of Distributed Systems

Networking & Communication

Data Storage & Databases

Performance & Scaling

System Architecture

Data Processing Systems

Reliability & Operations

Security

Trade-offs & Interview Thinking

Real-world Case Studies