What Makes an API RESTful: The Six Constraints and Common Real-World Violations
Explore Roy Fielding's six architectural REST constraints, cache semantics, layered systems, and where real production APIs break the specification.
On this page
Representational State Transfer (REST) is among the most widely cited and frequently misunderstood architectural patterns in software engineering. Introduced by Roy Fielding in his 2000 doctoral dissertation, REST was formulated not as a strict wire protocol, but as an architectural style: a coordinated set of architectural constraints applied to components, connectors, and data elements within a distributed hypermedia system.
In modern engineering conversations, virtually any JSON-over-HTTP endpoint is labelled a “REST API”. In reality, the vast majority of web services are Remote Procedure Call (RPC) interfaces masquerading under HTTP verbs. Understanding the six core constraints of REST reveals why the architecture was created, how it enables horizontal web-scale evolution, and where production systems deliberately break the rules.
+-------------------------------------------------------------+
| The Six REST Constraints |
+-------------------------------------------------------------+
| 1. Client-Server Separation | Decouples UI from persistence|
| 2. Statelessness | Every request contains state |
| 3. Cacheability | Explicit cache expiration |
| 4. Uniform Interface | Resources, URIs, Hypermedia |
| 5. Layered System | Transparent proxies & gates |
| 6. Code on Demand (Optional) | Client capability extension |
+-------------------------------------------------------------+
Constraint 1: Client-Server Separation
The client-server constraint enforces a strict separation of concerns. User interface concerns, rendering logic, and local state management belong entirely to the client. Data persistence, transactional integrity, and core business authorization belong exclusively to the server.
+------------------+ HTTP / TLS Network +--------------------+
| Mobile / SPA | =============================> | Backend Microservice|
| Client | <============================= | & Persistence Tier |
| (State & Render) | Representations | (Domain & DB Storage|
+------------------+ +--------------------+
By decoupling the user interface from data storage, client platforms can evolve across mobile native apps, browser single-page applications, and CLI tools without demanding modifications to backend storage layouts. Conversely, backend teams can migrate from relational engines to document datastores or distributed caches without breaking client interaction models.
Constraint 2: Statelessness
Statelessness mandates that each communication between client and server must contain all of the contextual information necessary to understand and complete the request. The server must not store any session state on its local disks or memory between successive requests.
+-------------------------------------------------------------------+
| Stateless Request Execution Model |
+-------------------------------------------------------------------+
| Client Request: |
| GET /v1/orders/8941 HTTP/1.1 |
| Host: api.example.com |
| Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn... |
| Idempotency-Key: 7b34e5a9-4d6b-4e1b-b4a1-0982736154ef |
+-------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------+
| Ingress Load Balancer: Routes to ANY available worker pod |
| [Pod A] [Pod B] [Pod C] [Pod D] |
| (No sticky sessions required; any worker can fulfill the request) |
+-------------------------------------------------------------------+
The Production Trade-Off
- Scalability Advantage: Application servers become purely stateless compute nodes. Traffic can be balanced across thousands of containers via round-robin without configuring sticky sessions. If a node crashes mid-session, adjacent pods fulfill subsequent requests without session replication overhead.
- Network Overhead: The client must repeatedly transmit authorization tokens, API keys, and context headers across every HTTP request, slightly increasing per-packet bandwidth.
Constraint 3: Cacheability
The cacheable constraint requires that response data within an interaction be implicitly or explicitly labelled as cacheable or non-cacheable. If a response is cacheable, a client or intermediate cache is granted the right to reuse that response data for later, equivalent requests.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=3600, stale-while-revalidate=60
ETag: W/"68b329-847291a"
Vary: Accept-Encoding, Authorization
{
"currency": "USD",
"exchange_rate": 1.0845,
"updated_at": "2026-11-15T08:00:00Z"
}
Caching eliminates client-perceived network round-trips and decouples read load from backend databases. When caching constraints are properly applied, downstream content delivery networks (CDNs) and forward proxies absorb 90% or more of read traffic, protecting primary databases from read exhaustion.
Constraint 4: Uniform Interface
The uniform interface is the defining constraint of REST. It establishes a standard, predictable contract between clients and servers. Fielding divided the uniform interface into four sub-requirements:
- Identification of Resources: Resources are conceptual entities identified by stable, unique Uniform Resource Identifiers (URIs), distinct from the underlying database representation.
- Manipulation of Resources through Representations: Clients hold a representation of a resource (such as JSON or XML) and mutate it by sending representations back to the server using standard HTTP methods (
POST,PUT,PATCH,DELETE). - Self-Descriptive Messages: Each message contains sufficient metadata for the recipient to parse it (such as
Content-Type: application/jsonandContent-Language: en-US). - Hypermedia as the Engine of Application State (HATEOAS): Clients transition between application states purely by discovering hyperlinks embedded dynamically within server responses.
{
"account_id": "act_99182",
"balance": 1540.50,
"status": "active",
"_links": {
"self": { "href": "/v1/accounts/act_99182" },
"deposit": { "href": "/v1/accounts/act_99182/deposits" },
"transfer": { "href": "/v1/accounts/act_99182/transfers" },
"close": { "href": "/v1/accounts/act_99182/closure" }
}
}
In strict HATEOAS, clients do not hardcode downstream endpoints. If an account is suspended, the server omits the "transfer" link, and client user interfaces dynamically disable the transfer action without hardcoded business rules.
Constraint 5: Layered System
The layered system constraint allows an architecture to be composed of hierarchical layers by restricting component behavior such that each component cannot see beyond the immediate layer with which it is interacting.
[Client]
|
v
[TLS Termination / CDN (Cloudflare)]
|
v
[Ingress Proxy / WAF (Envoy / AWS ALB)]
|
v
[API Gateway (Rate Limiting / Auth Token Introspection)]
|
v
[Stateless Application Pods]
|
v
[Read-Replica Distributed Database]
To the mobile app or browser, the entire backend appears as a single uniform endpoint. The client remains completely agnostic to whether its request was terminated by an edge cache, intercepted by a Web Application Firewall, or routed through an intermediate microservice proxy.
Constraint 6: Code on Demand (Optional)
Code on demand allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.
Server Response:
Content-Type: application/javascript
function validateTaxId(id) {
return /^[0-9]{9}$/.test(id);
}
While foundational to web browsers executing JavaScript downloaded from web servers, code on demand is deliberately disabled in enterprise API design. Mobile operating systems (such as iOS App Store guidelines) prohibit runtime execution of downloaded native code, and distributed microservices enforce strict sandboxing policies to prevent remote code execution vulnerabilities.
Where Real-World APIs Break the Constraints
Production engineering frequently forces compromises between pure architectural theory and operational reality:
+--------------------------------------------------------------------------+
| Common Production REST Violations & Root Causes |
+--------------------------------------------------------------------------+
| 1. Session State in In-Memory Caches: |
| Storing active shopping carts or user wizard steps in server-side |
| Redis clusters indexed by session ID violates strict statelessness. |
| |
| 2. Abandoning HATEOAS: |
| Clients hardcode URI paths (/v1/users/{id}) using client SDKs, |
| turning APIs into URI-RPC rather than true hypermedia engines. |
| |
| 3. RPC Endpoints Disguised as HTTP POST: |
| Using POST /api/calculateTax or POST /api/processBatch violates |
| resource-centric naming principles. |
| |
| 4. Missing or Broken Cache Headers: |
| Defaulting all dynamic JSON responses to Cache-Control: no-cache, |
| preventing edge networks from optimizing bandwidth. |
+--------------------------------------------------------------------------+
Architectural Review Checklist
When evaluating an API architecture against REST principles:
- Resource URIs: Are URIs formatted around plural nouns (
/v1/subscriptions) rather than imperative verbs (/v1/cancelSubscription)? - Stateless Tokens: Does each mutation pass authentication cryptographically (JWT or bearer token) without relying on sticky server sessions?
- HTTP Semantics: Are
GET,HEAD, andOPTIONSstrictly read-only and safe? ArePUTandDELETEstrictly idempotent? - RFC 7807 Errors: Do 4xx and 5xx responses return structured problem details with machine-readable status codes and error contexts?
- Caching Headers: Do entity read endpoints emit deterministic
ETagandLast-Modifiedheaders to enable conditional HTTP 304 Not Modified negotiations?
Frequently asked questions
What are the six architectural constraints defined in Roy Fielding's REST specification?
The six constraints are client-server separation, statelessness, cacheability, uniform interface, layered system, and the optional code-on-demand constraint.
Why do most modern web APIs fail to qualify as true REST according to Fielding?
Most modern APIs violate the uniform interface constraint by omitting HATEOAS (hypermedia controls) and storing session state on the server rather than maintaining strict request statelessness.
How does the layered system constraint protect client-side API consumers?
Layered systems allow proxies, API gateways, load balancers, and security firewalls to sit between client and server without altering the unified URI abstraction or client contract.
Why is code-on-demand considered the only optional constraint in REST?
Code-on-demand allows servers to transfer executable code (such as JavaScript applets) to extend client capabilities, but client environments may choose to disable dynamic code execution for security.



/* Comments */
Comments are offline right now — we reconnect automatically, nothing is lost.