Reference

REST API Principles

Comprehensive guide to REST architecture, constraints, design patterns, and the Richardson Maturity Model.

What is REST?

REST (Representational State Transfer) is an architectural style for designing networked applications. It was introduced by Roy Fielding in his 2000 doctoral dissertation.

Key Concept

REST is not a protocol or standard, but an architectural style. APIs that follow REST principles are called RESTful APIs.

REST Benefits

• Scalability through statelessness
• Performance via caching
• Simplicity and uniformity
• Platform independence
• Flexibility and evolvability

Common Uses

• Web services and APIs
• Mobile app backends
• Microservices communication
• Third-party integrations
• IoT device communication

Six REST Constraints

1. Client-Server Architecture

Separation of concerns between client (user interface) and server (data storage). They can evolve independently as long as the interface remains the same.

Benefits

• Portability: UI can run on multiple platforms
• Scalability: Server can handle multiple clients
• Independent evolution: Front-end and back-end can change separately

javascript

2. Statelessness

Each request from client to server must contain all information needed to understand and process the request. Server doesn't store client context between requests.

Benefits

• Scalability: Any server can handle any request
• Reliability: Easier recovery from failures
• Simplicity: No session state to manage

json

3. Cacheability

Responses must define themselves as cacheable or non-cacheable. If cacheable, client can reuse response data for equivalent requests.

Benefits

• Performance: Reduces server load and latency
• Bandwidth: Eliminates unnecessary data transfer
• Scalability: Fewer requests to process

json

4. Uniform Interface

Standardized way of communicating between client and server. This is the fundamental constraint that makes REST unique.

Resource Identification

Resources are identified by URIs (e.g., /users/123)

Resource Manipulation via Representations

Client holds representation (JSON, XML) and has enough info to modify/delete resource

Self-Descriptive Messages

Each message includes enough information to describe how to process it

HATEOAS

Hypermedia As The Engine Of Application State - responses include links to related resources

typescript

5. Layered System

Client cannot tell if it's connected directly to the end server or an intermediary. Allows for load balancers, proxies, gateways, and caches between client and server.

Benefits

• Scalability: Add load balancers as needed
• Security: Firewalls and proxies can filter traffic
• Legacy encapsulation: Hide old systems behind modern interfaces

plaintext

6. Code on Demand (Optional)

Server can extend client functionality by transferring executable code (e.g., JavaScript). This is the only optional constraint.

Note: Rarely used in modern REST APIs. Most APIs serve data, not executable code. However, web applications loading JavaScript from servers technically implement this.

Richardson Maturity Model

Leonard Richardson developed a maturity model that breaks down REST into levels, helping understand how "RESTful" an API really is.

Level 0

The Swamp of POX

POX = Plain Old XML. Uses HTTP as transport only. Single endpoint, single HTTP method (usually POST).

json

Level 1

Resources

Introduces multiple URIs for different resources. Still uses single HTTP method (POST).

json

Level 2

HTTP Verbs

Uses proper HTTP methods (GET, POST, PUT, DELETE) and status codes. Most "RESTful" APIs are here.

json

Level 3

Hypermedia Controls (HATEOAS)

Responses include links to related resources. Client discovers available actions from responses.

json

Which Level Should You Aim For?

Level 2 is the sweet spot for most APIs. It provides the core benefits of REST without the complexity of full hypermedia.

Level 3 (HATEOAS) is ideal for public APIs where you want maximum flexibility and discoverability, but adds complexity that many applications don't need.

Avoid Level 0-1 - they miss out on HTTP's capabilities and make APIs harder to use and understand.

Resource Design Patterns

Common Resource Patterns

http

REST vs Other API Styles

Comparison Table

Aspect	REST	GraphQL	gRPC
Protocol	HTTP/HTTPS	HTTP/HTTPS	HTTP/2
Data Format	JSON, XML	JSON	Protocol Buffers
Learning Curve	Easy	Medium	Steep
Caching	Built-in (HTTP)	Complex	Custom
Performance	Good	Good	Excellent
Browser Support	Full	Full	Limited
Best For	Public APIs, CRUD	Complex queries, mobile	Microservices, real-time
Tooling	Mature, widespread	Growing	Specialized

Common REST Mistakes

❌ Using Verbs in URLs

http

❌ Not Using HTTP Status Codes Properly

json

❌ Not Versioning APIs

plaintext

❌ Returning Arrays Directly

json

❌ Ignoring Security

http

REST API Best Practices

Use nouns for resources: /users, /products, /orders (not /getUsers)

Use plural names: /users (not /user) for consistency

Use proper HTTP methods: GET for read, POST for create, PUT/PATCH for update, DELETE for delete

Return proper status codes: 200, 201, 204, 400, 401, 403, 404, 422, 500

Version your API: Use /v1/, /v2/ in URL or headers

Use filtering & pagination: ?page=1&limit=20&sort=name&filter=active

Always use HTTPS: Encrypt all traffic

Implement rate limiting: Prevent abuse with proper headers

Use caching headers: Cache-Control, ETag for performance

Provide good documentation: OpenAPI/Swagger with examples

Handle errors gracefully: Consistent error format with details

Be stateless: Include all necessary info in each request

Previous: API Design Principles Next: API Versioning

What is REST?

REST (Representational State Transfer) is an architectural style for designing networked applications. It was introduced by Roy Fielding in his 2000 doctoral dissertation.

Key Concept

REST is not a protocol or standard, but an architectural style. APIs that follow REST principles are called RESTful APIs.

REST Benefits

• Scalability through statelessness
• Performance via caching
• Simplicity and uniformity
• Platform independence
• Flexibility and evolvability

Common Uses

• Web services and APIs
• Mobile app backends
• Microservices communication
• Third-party integrations
• IoT device communication

Six REST Constraints

1. Client-Server Architecture

Separation of concerns between client (user interface) and server (data storage). They can evolve independently as long as the interface remains the same.

Benefits

• Portability: UI can run on multiple platforms
• Scalability: Server can handle multiple clients
• Independent evolution: Front-end and back-end can change separately

javascript

2. Statelessness

Each request from client to server must contain all information needed to understand and process the request. Server doesn't store client context between requests.

Benefits

• Scalability: Any server can handle any request
• Reliability: Easier recovery from failures
• Simplicity: No session state to manage

json

3. Cacheability

Responses must define themselves as cacheable or non-cacheable. If cacheable, client can reuse response data for equivalent requests.

Benefits

• Performance: Reduces server load and latency
• Bandwidth: Eliminates unnecessary data transfer
• Scalability: Fewer requests to process

json

4. Uniform Interface

Standardized way of communicating between client and server. This is the fundamental constraint that makes REST unique.

Resource Identification

Resources are identified by URIs (e.g., /users/123)

Resource Manipulation via Representations

Client holds representation (JSON, XML) and has enough info to modify/delete resource

Self-Descriptive Messages

Each message includes enough information to describe how to process it

HATEOAS

Hypermedia As The Engine Of Application State - responses include links to related resources

typescript

5. Layered System

Client cannot tell if it's connected directly to the end server or an intermediary. Allows for load balancers, proxies, gateways, and caches between client and server.

Benefits

• Scalability: Add load balancers as needed
• Security: Firewalls and proxies can filter traffic
• Legacy encapsulation: Hide old systems behind modern interfaces

plaintext

6. Code on Demand (Optional)

Server can extend client functionality by transferring executable code (e.g., JavaScript). This is the only optional constraint.

Note: Rarely used in modern REST APIs. Most APIs serve data, not executable code. However, web applications loading JavaScript from servers technically implement this.

Richardson Maturity Model

Leonard Richardson developed a maturity model that breaks down REST into levels, helping understand how "RESTful" an API really is.

Level 0

The Swamp of POX

POX = Plain Old XML. Uses HTTP as transport only. Single endpoint, single HTTP method (usually POST).

json

Level 1

Resources

Introduces multiple URIs for different resources. Still uses single HTTP method (POST).

json

Level 2

HTTP Verbs

Uses proper HTTP methods (GET, POST, PUT, DELETE) and status codes. Most "RESTful" APIs are here.

json

Level 3

Hypermedia Controls (HATEOAS)

Responses include links to related resources. Client discovers available actions from responses.

json

Which Level Should You Aim For?

Level 2 is the sweet spot for most APIs. It provides the core benefits of REST without the complexity of full hypermedia.

Level 3 (HATEOAS) is ideal for public APIs where you want maximum flexibility and discoverability, but adds complexity that many applications don't need.

Avoid Level 0-1 - they miss out on HTTP's capabilities and make APIs harder to use and understand.

REST vs Other API Styles

Comparison Table

Aspect	REST	GraphQL	gRPC
Protocol	HTTP/HTTPS	HTTP/HTTPS	HTTP/2
Data Format	JSON, XML	JSON	Protocol Buffers
Learning Curve	Easy	Medium	Steep
Caching	Built-in (HTTP)	Complex	Custom
Performance	Good	Good	Excellent
Browser Support	Full	Full	Limited
Best For	Public APIs, CRUD	Complex queries, mobile	Microservices, real-time
Tooling	Mature, widespread	Growing	Specialized