REST API Design

In the year 2000, Roy Thomas Fielding published his doctoral dissertation, "Architectural Styles and the Design of Network-based Software Architectures." Chapter 5 of that dissertation introduced Representational State Transfer (REST)—an architectural style that would fundamentally reshape how the world builds distributed systems.

Today, REST has become so ubiquitous that many developers use the term without fully understanding its meaning. APIs are casually labeled "RESTful" when they merely use HTTP and JSON, missing the profound architectural principles that make REST powerful. This misunderstanding leads to APIs that are fragile, tightly coupled, and difficult to evolve.

To design APIs that stand the test of time—that scale, evolve gracefully, and delight developers who consume them—we must return to the source. We must understand REST not as a technology or a protocol, but as an architectural style defined by specific constraints that, when properly applied, produce systems with remarkable properties.

Before diving into constraints, we must establish what REST fundamentally is—and what it is not.

REST is an architectural style, not a protocol or framework.

Roy Fielding derived REST by analyzing what made the early Web successful. He identified the architectural properties that enabled the Web to scale from a few academic servers to billions of connected devices. REST is a description of those properties, expressed as constraints on how components interact.

This distinction matters enormously. A protocol specifies exact message formats and behaviors. An architectural style provides guidelines for constructing systems with desired properties. REST doesn't mandate HTTP, JSON, or any specific technology. It describes a set of constraints that, when applied, produce systems with properties like:

• Performance — efficient network usage through caching and layered processing
• Scalability — stateless servers that can be replicated without coordination
• Simplicity — a uniform interface that reduces cognitive load
• Modifiability — loose coupling that allows components to evolve independently
• Visibility — intermediaries can observe and optimize interactions
• Portability — components can be moved across deployment environments
• Reliability — failures in one component don't cascade to others

The Richardson Maturity Model

Leonard Richardson proposed a model for classifying APIs by their adherence to REST principles. This model helps us understand the spectrum from "not REST at all" to "fully RESTful":

Level 3 is "true" REST as Fielding envisioned it. Most production APIs today operate at Level 2, which provides significant benefits but misses REST's most powerful feature: hypermedia-driven discovery.

Fielding defined REST through six architectural constraints. Each constraint is deliberately chosen to induce specific architectural properties. Understanding the why behind each constraint is essential for making intelligent tradeoffs when designing APIs.

Let's examine each constraint in depth:

Let's examine each constraint in detail, understanding both the principle and its practical implications.

The client-server constraint establishes the foundational separation of concerns in REST architectures:

The Principle: Clients are concerned with user interface and user state. Servers are concerned with data storage, domain logic, and business rules. These concerns are separated by a uniform interface, allowing each to evolve independently.

Why This Matters:

This separation seems obvious today, but it wasn't always the norm. Early distributed systems often blurred these responsibilities. The client-server constraint enables:

1. Independent Evolution — Mobile apps, web apps, and CLI tools can all consume the same API
2. Portability — User interfaces can be deployed across platforms without server changes
3. Scalability — Servers can be replicated and load-balanced transparently
4. Organizational Scaling — Different teams can own clients and servers with clear contracts

The stateless constraint is perhaps the most impactful—and most frequently violated—of all REST constraints.

The Principle: Each request from client to server must contain all the information necessary to understand and process that request. The server cannot rely on any stored context from previous requests. Session state, if needed, must be kept entirely on the client.

Why This Matters:

Statelessness induces several critical architectural properties:

Common Statelessness Violations:

• Server-side sessions — Storing cart contents, wizard progress, or view preferences on the server
• Implicit pagination cursors — When GET /items?page=2 means different things based on prior /items?page=1 calls
• Multi-step transactions — "Add to cart, then checkout" where checkout assumes server remembers cart
• Sticky load balancing — Required only because servers hold client state

Acceptable State:

Statelessness refers to application state, not resource state. The database obviously holds state. The constraint is that servers shouldn't hold client session state between requests. Each request must be self-sufficient.

The cache constraint transforms REST from merely functional to performant at global scale.

The Principle: Responses must explicitly or implicitly define themselves as cacheable or non-cacheable. When a response is cacheable, clients and intermediaries may reuse that response for equivalent future requests.

Why This Matters:

Caching is the single most effective technique for improving distributed system performance. The cache constraint:

1. Reduces Latency — Cached responses arrive in milliseconds rather than round-trips
2. Decreases Server Load — Identical requests don't hit the origin
3. Improves Reliability — Stale cache can serve during origin outages
4. Saves Bandwidth — No data transfer for cached responses

The uniform interface is REST's central distinguishing feature—the characteristic that most differentiates it from other distributed architecture styles.

The Principle: All components in a REST architecture interact through the same standardized interface, regardless of what resources they access or what operations they perform. This uniformity simplifies the architecture and improves visibility.

Fielding defined four sub-constraints that together constitute the uniform interface:

4.1 Identification of Resources

Resources are named by URIs. A resource is any concept that can be named—a document, an image, a collection, a computed result, a business entity. The URI identifies the resource, not the representation.

/users/12345           — A specific user
/users                 — Collection of users
/users/12345/orders    — Orders belonging to a user
/search?q=widgets     — A computed search result

4.2 Manipulation Through Representations

Clients interact with resources through representations (JSON, XML, HTML, etc.). When a client wants to modify a resource, it sends a representation of the desired state. The server then validates and applies that change.

4.3 Self-Descriptive Messages

Each message contains enough information to describe how to process it. Media types, HTTP methods, and headers all contribute to self-description. An intermediary should be able to understand what a request does without application-specific knowledge.

4.4 Hypermedia as the Engine of Application State (HATEOAS)

Clients discover available actions through hypermedia links in responses. Instead of hardcoding API URLs, clients follow links to transition between application states. This is REST's most under-implemented—and most powerful—constraint.

The layered system constraint organizes the architecture hierarchically, where each layer only knows about its immediate neighbors.

The Principle: A client cannot tell whether it's connected directly to the origin server or to an intermediary. Each component only sees the layer it interacts with directly. Intermediaries can be added transparently for load balancing, caching, security, and other cross-cutting concerns.

Why This Matters:

Layering enables architectural evolution without client changes:

┌─────────────────────────────────────────────────────────────────┐
│  Client                                                          │
│  (Only knows it talks to "the API")                             │
└─────────────────── │ ────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│  CDN Edge (Cloudflare/Fastly)                                    │
│  - Static asset caching                                          │
│  - DDoS protection                                               │
│  - Geographic latency reduction                                  │
└─────────────────── │ ────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│  API Gateway (Kong/Ambassador)                                   │
│  - Rate limiting                                                 │
│  - Authentication                                                │
│  - Request routing                                               │
│  - Protocol translation                                          │
└─────────────────── │ ────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│  Load Balancer                                                   │
│  - Health checking                                               │
│  - Traffic distribution                                          │
│  - Failover                                                      │
└─────────────────── │ ────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────────┐
│  Application Servers (Origin)                                    │
│  - Business logic                                                │
│  - Data access                                                   │
└─────────────────────────────────────────────────────────────────┘

The final REST constraint is the only optional one. Code-on-demand allows servers to extend client functionality by transferring executable code.

The Principle: Servers can temporarily extend or customize client functionality by transferring executable code (scripts, applets). Clients don't need to pre-understand all possible features—they can be extended at runtime.

Historical Context:

This is exactly what happens when a web browser loads JavaScript from a server. The browser doesn't know in advance what code it will execute; it downloads and runs whatever the server provides. This transformed the early Web from a static document viewer into a rich application platform.

Why It's Optional:

Code-on-demand is optional because it reduces visibility—intermediaries can't inspect and optimize code that they don't understand. It also creates security concerns, which is why browsers sandbox JavaScript so aggressively.

For modern APIs, code-on-demand manifests in several ways:

REST's power emerges from how constraints work together. Each constraint alone provides some benefit; together, they create systems with emergent properties that no single constraint could achieve.

Synergy Example: Scalability

Scalability in REST isn't a single feature—it emerges from multiple constraints:

1. Statelessness — No session synchronization between servers
2. Cacheability — Frequently-accessed resources served from cache
3. Layered System — Load balancers distribute traffic transparently
4. Uniform Interface — Any server can handle any request

Remove any one constraint, and scalability suffers. Stateful sessions require affinity. Uncacheable responses demand origin hits. Opaque layers prevent routing optimization. Non-uniform interfaces require specialized handlers.

We've covered the theoretical foundation of REST. Let's consolidate what we've learned:

What's Next:

Now that we understand REST's theoretical foundation, we'll explore how to apply these principles through resource-based design. You'll learn how to model your domain as resources, design intuitive URIs, and structure relationships between resources.