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
AspectRESTGraphQLgRPC
ProtocolHTTP/HTTPSHTTP/HTTPSHTTP/2
Data FormatJSON, XMLJSONProtocol Buffers
Learning CurveEasyMediumSteep
CachingBuilt-in (HTTP)ComplexCustom
PerformanceGoodGoodExcellent
Browser SupportFullFullLimited
Best ForPublic APIs, CRUDComplex queries, mobileMicroservices, real-time
ToolingMature, widespreadGrowingSpecialized

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 PrinciplesNext: API Versioning