Understanding REST Architecture
1. Understanding REST Principles
REST (Representational State Transfer) is an architectural style for distributed hypermedia systems defined by Roy Fielding (2000). It is not a protocol or standard but a set of constraints.
| Constraint | Description | Required |
|---|---|---|
| Client-Server | Separation of concerns; UI vs data storage | Yes |
| Stateless | Each request contains all info needed; no server session state | Yes |
| Cacheable | Responses must be implicitly/explicitly cacheable or not | Yes |
| Uniform Interface | Standardized methods, identifiers, hypermedia | Yes |
| Layered System | Client cannot tell if connected to end server or intermediary | Yes |
| Code on Demand | Server can extend client by transferring executable code | Optional |
2. Understanding Resource-Based Architecture
Everything is a resource identified by a URI. Resources are nouns; verbs come from HTTP methods.
| Concept | Definition | Example |
|---|---|---|
| Resource | Any addressable entity (user, order, product) | /users/42 |
| Resource Identifier | URI uniquely identifying a resource | https://api.example.com/orders/100 |
| Representation | Serialized form of resource state | JSON, XML, HTML |
| Collection | Container of resources | /users |
| Singleton | One-of-a-kind resource | /users/42/profile |
3. Understanding Uniform Interface Constraints
| Sub-Constraint | Meaning |
|---|---|
| Identification of Resources | Each resource has a unique URI |
| Manipulation via Representations | Clients modify resources by sending representations |
| Self-Descriptive Messages | Each message has enough info to process it (Content-Type, etc.) |
| HATEOAS | Responses include links to discover next actions |
4. Understanding Stateless Communication
Server stores no client context between requests. Session state lives on the client.
| Aspect | Stateless (REST) | Stateful |
|---|---|---|
| Auth | Token sent every request | Server-side session |
| Scalability | Horizontal scaling trivial | Sticky sessions required |
| Reliability | Server failure does not lose state | State lost on failure |
| Bandwidth | Higher (full context per request) | Lower |
Warning: Cookies/sessions stored server-side violate statelessness. Use JWT/Bearer tokens instead.
5. Understanding Cacheability Requirements
| Method | Cacheable by Default | Notes |
|---|---|---|
| GET | Yes | Cache freely with proper headers |
| HEAD | Yes | Same as GET, no body |
| POST | Conditional | Only if explicit Cache-Control set |
| PUT/PATCH/DELETE | No | Mutating operations |
6. Understanding Layered System Architecture
Client → CDN → API Gateway → Load Balancer → App Server → DB
(cache) (auth/rate) (routing) (business)
| Layer | Purpose |
|---|---|
| CDN | Edge caching, static asset delivery |
| API Gateway | Auth, rate limiting, routing |
| Load Balancer | Distribute traffic across instances |
| Application | Business logic |
| Data Store | Persistence layer |
7. Understanding Code on Demand
Optional constraint: server delivers executable code (JavaScript, applets) to extend client functionality.
| Use Case | Example | Status |
|---|---|---|
| Browser JS | Server returns HTML+JS bundle | Common |
| Plugins | Java applets, Flash | Obsolete |
| WebAssembly | Compiled modules served by API | Modern |
8. Understanding REST Maturity Model
Richardson Maturity Model (RMM) measures how RESTful an API is.
| Level | Name | Characteristic |
|---|---|---|
| 0 | Swamp of POX | One URI, one method (POST), RPC-style |
| 1 | Resources | Multiple URIs, still single method |
| 2 | HTTP Verbs | Proper use of GET/POST/PUT/DELETE + status codes |
| 3 | Hypermedia (HATEOAS) | Responses include links to related actions |
9. Understanding RESTful vs REST-like APIs
| Aspect | RESTful (Strict) | REST-like (Pragmatic) |
|---|---|---|
| HATEOAS | Required | Optional/omitted |
| Hypermedia | Discoverable | Documented out-of-band |
| Adoption | Rare | Most public APIs (GitHub, Stripe) |
| Maturity Level | 3 | 2 |
10. Understanding REST vs SOAP Differences
| Feature | REST | SOAP |
|---|---|---|
| Protocol | HTTP only | HTTP, SMTP, TCP |
| Format | JSON, XML, anything | XML only |
| Style | Architectural style | Protocol with strict spec |
| Standards | Conventions, OpenAPI | WSDL, WS-* (Security, AT) |
| Performance | Lighter, cacheable | Heavier (XML envelope) |
| Use Case | Web/mobile APIs | Enterprise, banking, legacy |
| Error Handling | HTTP status codes | SOAP Fault element |