System Design (HLD)REST API Design

REST API Design

LevelIntermediate

Duration90 mins

TopicREST API Design

1 / 5

REST Principles and Constraints

The Architectural Style That Powers the Web

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.

What You Will Learn

By the end of this page, you will understand REST as Roy Fielding envisioned it—not as a vague synonym for HTTP APIs, but as a rigorous architectural style. You'll learn the six constraints that define REST, why each constraint exists, and how they combine to produce systems that are scalable, evolvable, and resilient.

What REST Actually Is

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 RESTful API Misnomer

Most "RESTful APIs" in the wild would be more accurately called "HTTP-based APIs" or "JSON over HTTP." They use HTTP verbs and status codes but ignore crucial REST constraints like hypermedia (HATEOAS). This isn't necessarily wrong—sometimes full REST is unnecessary—but developers should understand what they're trading away.

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	Name	Description	Example
0	The Swamp of POX	Single URI, single HTTP method, tunneled all operations	SOAP/XML-RPC over POST
1	Resources	Multiple URIs representing different resources	/users, /orders separate endpoints
2	HTTP Verbs	Proper use of HTTP methods (GET, POST, PUT, DELETE)	GET /users vs POST /users
3	Hypermedia Controls	Responses include links to related actions/resources	HATEOAS fully implemented

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.

The Six REST Constraints

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:

The Six REST Constraints

•1. Client-Server — Separation of concerns between user interface and data storage
•2. Stateless — Each request contains all information needed to process it
•3. Cacheable — Responses explicitly indicate their cacheability
•4. Uniform Interface — A standardized interaction model between components
•5. Layered System — Components only see the immediate layer they interact with
•6. Code-On-Demand (Optional) — Servers can extend client functionality with executable code

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

Constraint 1: Client-Server Separation

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:

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

Client Responsibilities

•User interface rendering
•User input handling
•Local state management
•Request construction
•Response interpretation
•Error presentation

Server Responsibilities

•Data persistence
•Business logic execution
•Authorization enforcement
•Resource state management
•Response generation
•Integration coordination

Practical Implication

The client-server constraint implies that your API should expose resources and operations, not UI-specific data structures. If your API returns pre-formatted HTML snippets or screen-specific response shapes, you've violated this constraint. The server shouldn't know whether the client is a mobile app, a web page, or a command-line tool.

Constraint 2: Statelessness

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:

Property	How Statelessness Enables It
Scalability	Any server can handle any request—no session affinity required
Reliability	Server failures don't cause session loss; clients can retry elsewhere
Visibility	Intermediaries can understand requests without session context
Simplicity	Servers need less memory; no session synchronization complexity

stateless-vs-stateful.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ❌ STATEFUL ANTI-PATTERN: Server remembers client context
// Session stored on server
app.post('/cart/add', (req, res) => {
    const session = sessions[req.sessionId]; // Server-stored state
    session.cart.push(req.body.item);        // Modifies session on server
    res.json({ success: true });
});
 
// This creates problems:
// - Can't load-balance without sticky sessions
// - Server memory grows with active users
// - Server restart loses all sessions
 
 
// ✅ STATELESS PATTERN: All context in request
app.post('/cart/add', authenticateJWT, (req, res) => {
    // User identity comes from JWT token (in request)
    const userId = req.user.id;
    
    // Cart state is persisted in database, not server memory
    const cart = await cartRepository.findByUser(userId);
    cart.addItem(req.body.item);
    await cartRepository.save(cart);
    
    res.json({ cart: cart.toJSON() });
});
 
// Benefits:
// - Any server can handle the request
// - Horizontal scaling is trivial
// - No session synchronization required

The Cost of Statelessness

Statelessness isn't free. Every request must carry authentication tokens, potentially increasing bandwidth. Clients must manage state they would otherwise offload to servers. This is a deliberate tradeoff: REST accepts increased per-request overhead to gain scalability and reliability. For most web-scale systems, this tradeoff is overwhelmingly worthwhile.

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.

Constraint 3: Cacheability

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:

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

cache-headers.http
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# CACHEABLE RESPONSE - Product catalog (changes rarely)
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=3600, stale-while-revalidate=86400
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Tue, 07 Jan 2025 12:00:00 GMT
Vary: Accept-Encoding
 
# Cache-Control directives explained:
# - public: CDNs and proxies can cache this
# - max-age=3600: Fresh for 1 hour
# - stale-while-revalidate=86400: Can serve stale for 1 day while revalidating
 
 
# NON-CACHEABLE RESPONSE - User's bank balance
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-store, no-cache, must-revalidate
Pragma: no-cache
 
# - private: Only client can cache (not CDNs)
# - no-store: Don't persist to disk
# - no-cache: Always revalidate before use
# - must-revalidate: Never serve stale
 
 
# CONDITIONAL REQUEST - Bandwidth-efficient revalidation
GET /api/products/12345 HTTP/1.1
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-Modified-Since: Tue, 07 Jan 2025 12:00:00 GMT
 
# Server response if unchanged (saves bandwidth):
HTTP/1.1 304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Cache-Control Directives
Directive	Meaning	Use Case
public	Any cache may store	Static assets, public content
private	Only client may cache	User-specific data
max-age=N	Fresh for N seconds	Content with known freshness
s-maxage=N	CDN-specific max-age	Different CDN vs browser timing
no-cache	Must revalidate before use	Data that changes frequently
no-store	Never persist to disk	Sensitive/financial data
must-revalidate	Never serve stale	Critical data accuracy
stale-while-revalidate=N	Serve stale while refreshing	Perceived performance
immutable	Never revalidate	Versioned static assets

ETags vs Last-Modified

ETags are content-based (hash of response body), while Last-Modified is time-based. ETags are more precise—they detect changes even if the modification time is wrong. Use both when possible; HTTP allows clients to send both If-None-Match and If-Modified-Since, with ETag taking precedence.

Constraint 4: Uniform Interface

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.

hateoas-example.json
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "orderId": "ord-123",
    "status": "pending_payment",
    "total": {
        "amount": 99.99,
        "currency": "USD"
    },
    "items": [
        {"product": "Widget", "quantity": 2, "price": 49.995}
    ],
    "_links": {
        "self": {
            "href": "/orders/ord-123"
        },
        "pay": {
            "href": "/orders/ord-123/payments",
            "method": "POST",
            "title": "Submit payment for this order"
        },
        "cancel": {
            "href": "/orders/ord-123",
            "method": "DELETE",
            "title": "Cancel this order"
        },
        "customer": {
            "href": "/customers/cust-456"
        },
        "items": {
            "href": "/orders/ord-123/items"
        }
    }
}

Why HATEOAS Matters

HATEOAS decouples clients from server URL structures. If the server changes /orders/{id}/payment to /payments/orders/{id}, HATEOAS clients continue working—they follow links rather than constructing URLs. This enables servers to evolve independently of clients, which is crucial for long-lived public APIs.

Constraint 5: Layered System

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                                                   │
└─────────────────────────────────────────────────────────────────┘

Benefits of Layered Architecture

•Security in Depth — Multiple layers can enforce independent security checks
•Encapsulation — Legacy systems can be wrapped without exposing their complexity
•Scalability — Each layer can scale independently based on its specific demands
•Flexibility — Intermediaries can be added/removed without client changes
•Simplified Components — Each layer handles a focused set of responsibilities

The Latency Cost

Layering adds latency—each hop takes time. This is typically offset by caching, but deep layer stacks can introduce measurable overhead. Modern architectures often collapse layers for performance-critical paths while maintaining the layered model for non-critical traffic.

Constraint 6: Code-On-Demand (Optional)

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:

Pattern	Description	Example
JavaScript embedding	Web pages load scripts from APIs	Analytics SDKs, embedded widgets
WebAssembly	Binary code executed in browser	Image processing, cryptography
Configuration-as-code	Server-sent rules interpreted by client	Feature flags, A/B test variants
Lambda execution	Server-defined logic run client-side	Smart form validation rules

Modern Code-On-Demand

While classical code-on-demand has security implications, modern interpretations are more constrained. JSON schemas that describe validation rules, GraphQL schemas that clients interpret, and configuration objects that control client behavior are all forms of code-on-demand—they extend client functionality through server-provided definitions.

How Constraints Combine

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:

Statelessness — No session synchronization between servers
Cacheability — Frequently-accessed resources served from cache
Layered System — Load balancers distribute traffic transparently
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.

Constraint Interactions
Constraint Pair	Combined Property	What Happens If One Is Missing
Stateless + Cacheable	Efficient scaling	Cache invalidation becomes complex per-user
Uniform Interface + Layered	Transparent intermediaries	Proxies can't understand or optimize requests
Client-Server + Stateless	Independent evolution	Server becomes tied to client session format
Cacheable + Layered	CDN acceleration	Every request must reach origin
Uniform + Cacheable	Content negotiation caching	Cache keys become application-specific

The Richardson Maturity Path

Teams often adopt REST incrementally. Level 2 (resources + HTTP verbs) is where most production APIs stabilize. Moving to Level 3 (HATEOAS) provides maximum flexibility but requires more sophisticated clients. The key is understanding what properties you need and which constraints enable them.

Summary: REST's Foundation

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

Key Takeaways

•REST is an architectural style, not a protocol — It describes constraints that produce systems with desirable properties
•Six constraints define REST — Client-Server, Stateless, Cacheable, Uniform Interface, Layered System, and (optional) Code-On-Demand
•Statelessness enables horizontal scaling — Each request is self-contained, allowing any server to handle it
•Cacheability enables performance — Responses declare their freshness; clients and proxies can reuse them
•Uniform Interface enables loose coupling — Resources, representations, self-description, and hypermedia standardize interactions
•Constraints synergize — The combination produces scalability, evolvability, and reliability that no single constraint could achieve
•Most APIs are Level 2 — They use resources and HTTP verbs but skip HATEOAS; this is often acceptable but should be a conscious choice

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.

Page Complete

You now understand REST as Roy Fielding envisioned it—not as a vague label for HTTP APIs, but as a rigorous architectural style with specific constraints that produce scalable, evolvable, and resilient systems. Next, we'll translate these principles into practical resource design.

1 / 5

Loading learning content...

System Design (HLD)REST API Design

REST API Design

LevelIntermediate

Duration90 mins

TopicREST API Design

1 / 5

REST Principles and Constraints

The Architectural Style That Powers the Web

What You Will Learn

What REST Actually Is

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.

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 RESTful API Misnomer

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	Name	Description	Example
0	The Swamp of POX	Single URI, single HTTP method, tunneled all operations	SOAP/XML-RPC over POST
1	Resources	Multiple URIs representing different resources	/users, /orders separate endpoints
2	HTTP Verbs	Proper use of HTTP methods (GET, POST, PUT, DELETE)	GET /users vs POST /users
3	Hypermedia Controls	Responses include links to related actions/resources	HATEOAS fully implemented

The Six REST Constraints

Let's examine each constraint in depth:

The Six REST Constraints

•1. Client-Server — Separation of concerns between user interface and data storage
•2. Stateless — Each request contains all information needed to process it
•3. Cacheable — Responses explicitly indicate their cacheability
•4. Uniform Interface — A standardized interaction model between components
•5. Layered System — Components only see the immediate layer they interact with
•6. Code-On-Demand (Optional) — Servers can extend client functionality with executable code

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

Constraint 1: Client-Server Separation

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

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:

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

Client Responsibilities

•User interface rendering
•User input handling
•Local state management
•Request construction
•Response interpretation
•Error presentation

Server Responsibilities

•Data persistence
•Business logic execution
•Authorization enforcement
•Resource state management
•Response generation
•Integration coordination

Practical Implication

Constraint 2: Statelessness

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

Why This Matters:

Statelessness induces several critical architectural properties:

Property	How Statelessness Enables It
Scalability	Any server can handle any request—no session affinity required
Reliability	Server failures don't cause session loss; clients can retry elsewhere
Visibility	Intermediaries can understand requests without session context
Simplicity	Servers need less memory; no session synchronization complexity

stateless-vs-stateful.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ❌ STATEFUL ANTI-PATTERN: Server remembers client context
// Session stored on server
app.post('/cart/add', (req, res) => {
    const session = sessions[req.sessionId]; // Server-stored state
    session.cart.push(req.body.item);        // Modifies session on server
    res.json({ success: true });
});
 
// This creates problems:
// - Can't load-balance without sticky sessions
// - Server memory grows with active users
// - Server restart loses all sessions
 
 
// ✅ STATELESS PATTERN: All context in request
app.post('/cart/add', authenticateJWT, (req, res) => {
    // User identity comes from JWT token (in request)
    const userId = req.user.id;
    
    // Cart state is persisted in database, not server memory
    const cart = await cartRepository.findByUser(userId);
    cart.addItem(req.body.item);
    await cartRepository.save(cart);
    
    res.json({ cart: cart.toJSON() });
});
 
// Benefits:
// - Any server can handle the request
// - Horizontal scaling is trivial
// - No session synchronization required

The Cost of Statelessness

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:

Constraint 3: Cacheability

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

Why This Matters:

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

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

cache-headers.http
HTTP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# CACHEABLE RESPONSE - Product catalog (changes rarely)
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=3600, stale-while-revalidate=86400
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Tue, 07 Jan 2025 12:00:00 GMT
Vary: Accept-Encoding
 
# Cache-Control directives explained:
# - public: CDNs and proxies can cache this
# - max-age=3600: Fresh for 1 hour
# - stale-while-revalidate=86400: Can serve stale for 1 day while revalidating
 
 
# NON-CACHEABLE RESPONSE - User's bank balance
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-store, no-cache, must-revalidate
Pragma: no-cache
 
# - private: Only client can cache (not CDNs)
# - no-store: Don't persist to disk
# - no-cache: Always revalidate before use
# - must-revalidate: Never serve stale
 
 
# CONDITIONAL REQUEST - Bandwidth-efficient revalidation
GET /api/products/12345 HTTP/1.1
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-Modified-Since: Tue, 07 Jan 2025 12:00:00 GMT
 
# Server response if unchanged (saves bandwidth):
HTTP/1.1 304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Cache-Control Directives
Directive	Meaning	Use Case
public	Any cache may store	Static assets, public content
private	Only client may cache	User-specific data
max-age=N	Fresh for N seconds	Content with known freshness
s-maxage=N	CDN-specific max-age	Different CDN vs browser timing
no-cache	Must revalidate before use	Data that changes frequently
no-store	Never persist to disk	Sensitive/financial data
must-revalidate	Never serve stale	Critical data accuracy
stale-while-revalidate=N	Serve stale while refreshing	Perceived performance
immutable	Never revalidate	Versioned static assets

ETags vs Last-Modified

Constraint 4: Uniform Interface

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

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

4.1 Identification of Resources

/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

4.3 Self-Descriptive Messages

4.4 Hypermedia as the Engine of Application State (HATEOAS)

hateoas-example.json
JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "orderId": "ord-123",
    "status": "pending_payment",
    "total": {
        "amount": 99.99,
        "currency": "USD"
    },
    "items": [
        {"product": "Widget", "quantity": 2, "price": 49.995}
    ],
    "_links": {
        "self": {
            "href": "/orders/ord-123"
        },
        "pay": {
            "href": "/orders/ord-123/payments",
            "method": "POST",
            "title": "Submit payment for this order"
        },
        "cancel": {
            "href": "/orders/ord-123",
            "method": "DELETE",
            "title": "Cancel this order"
        },
        "customer": {
            "href": "/customers/cust-456"
        },
        "items": {
            "href": "/orders/ord-123/items"
        }
    }
}

Why HATEOAS Matters

Constraint 5: Layered System

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

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                                                   │
└─────────────────────────────────────────────────────────────────┘

Benefits of Layered Architecture

•Security in Depth — Multiple layers can enforce independent security checks
•Encapsulation — Legacy systems can be wrapped without exposing their complexity
•Scalability — Each layer can scale independently based on its specific demands
•Flexibility — Intermediaries can be added/removed without client changes
•Simplified Components — Each layer handles a focused set of responsibilities

The Latency Cost

Constraint 6: Code-On-Demand (Optional)

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

Historical Context:

Why It's Optional:

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

Pattern	Description	Example
JavaScript embedding	Web pages load scripts from APIs	Analytics SDKs, embedded widgets
WebAssembly	Binary code executed in browser	Image processing, cryptography
Configuration-as-code	Server-sent rules interpreted by client	Feature flags, A/B test variants
Lambda execution	Server-defined logic run client-side	Smart form validation rules

Modern Code-On-Demand

How Constraints Combine

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:

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

Constraint Interactions
Constraint Pair	Combined Property	What Happens If One Is Missing
Stateless + Cacheable	Efficient scaling	Cache invalidation becomes complex per-user
Uniform Interface + Layered	Transparent intermediaries	Proxies can't understand or optimize requests
Client-Server + Stateless	Independent evolution	Server becomes tied to client session format
Cacheable + Layered	CDN acceleration	Every request must reach origin
Uniform + Cacheable	Content negotiation caching	Cache keys become application-specific

The Richardson Maturity Path

Summary: REST's Foundation

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

Key Takeaways

•REST is an architectural style, not a protocol — It describes constraints that produce systems with desirable properties
•Six constraints define REST — Client-Server, Stateless, Cacheable, Uniform Interface, Layered System, and (optional) Code-On-Demand
•Statelessness enables horizontal scaling — Each request is self-contained, allowing any server to handle it
•Cacheability enables performance — Responses declare their freshness; clients and proxies can reuse them
•Uniform Interface enables loose coupling — Resources, representations, self-description, and hypermedia standardize interactions
•Constraints synergize — The combination produces scalability, evolvability, and reliability that no single constraint could achieve
•Most APIs are Level 2 — They use resources and HTTP verbs but skip HATEOAS; this is often acceptable but should be a conscious choice

What's Next:

Page Complete

1 / 5