REST Deep Dive¶
Level: Intermediate
Pre-reading: 05 · API & Communication
REST Fundamentals¶
REST (Representational State Transfer) is an architectural style for designing networked applications. It uses HTTP methods to perform operations on resources.
Richardson Maturity Model¶
A model for measuring how RESTful an API is:
graph TD
L0[Level 0: Swamp of POX]
L1[Level 1: Resources]
L2[Level 2: HTTP Verbs]
L3[Level 3: HATEOAS]
L0 --> L1 --> L2 --> L3
| Level | Description | Example |
|---|---|---|
| Level 0 | Single endpoint; RPC over HTTP | POST /api with action in body |
| Level 1 | Resources with URIs | /orders, /customers |
| Level 2 | HTTP verbs + status codes | GET, POST, PUT, DELETE; 201, 404 |
| Level 3 | HATEOAS (hypermedia) | Links in responses for navigation |
Level 2 Example¶
GET /orders/123 HTTP/1.1
Host: api.example.com
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "123",
"status": "placed",
"total": 99.99
}
Level 3 Example (HATEOAS)¶
{
"id": "123",
"status": "placed",
"total": 99.99,
"_links": {
"self": { "href": "/orders/123" },
"cancel": { "href": "/orders/123/cancel", "method": "POST" },
"items": { "href": "/orders/123/items" },
"customer": { "href": "/customers/456" }
}
}
flowchart LR
L0["<b>Level 0</b> — POX<br/>one URI, one verb (POST)<br/>RPC over HTTP"]
L1["<b>Level 1</b> — Resources<br/>many URIs (nouns)<br/>still one verb"]
L2["<b>Level 2</b> — Verbs + status codes<br/>GET/POST/PUT/DELETE<br/>201 · 404 · 409"]
L3["<b>Level 3</b> — HATEOAS<br/>responses carry links<br/>to valid next actions"]
L0 --> L1 --> L2 --> L3
style L2 fill:#d5e8d4
style L3 fill:#dae8fc
HTTP Methods¶
| Method | Purpose | Idempotent | Safe |
|---|---|---|---|
| GET | Retrieve resource | Yes | Yes |
| POST | Create resource | No | No |
| PUT | Replace resource | Yes | No |
| PATCH | Partial update | No* | No |
| DELETE | Remove resource | Yes | No |
| HEAD | Get headers only | Yes | Yes |
| OPTIONS | Get allowed methods | Yes | Yes |
*PATCH can be idempotent with JSON Patch operations
PUT vs PATCH¶
# PUT: Replace entire resource
PUT /orders/123
{
"status": "shipped",
"items": [...],
"shippingAddress": {...}
}
# PATCH: Update specific fields
PATCH /orders/123
{
"status": "shipped"
}
Status Codes¶
| Range | Category | Common Codes |
|---|---|---|
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirect | 301 Moved, 304 Not Modified |
| 4xx | Client Error | 400 Bad Request, 401, 403, 404, 409 Conflict, 429 |
| 5xx | Server Error | 500 Internal, 502 Bad Gateway, 503 Unavailable |
Status Code Guidelines¶
| Action | Success | Failure |
|---|---|---|
| GET | 200 OK | 404 Not Found |
| POST | 201 Created | 400 Bad Request, 409 Conflict |
| PUT | 200 OK / 204 No Content | 404, 400 |
| DELETE | 204 No Content | 404 |
| PATCH | 200 OK | 400, 404 |
Idempotency¶
An idempotent operation produces the same result when called multiple times.
| Method | Idempotent? | Why |
|---|---|---|
| GET | Yes | Returns same data |
| PUT | Yes | Same resource state |
| DELETE | Yes | Resource stays deleted |
| POST | No | Creates new resource each time |
Idempotency Keys¶
For non-idempotent operations, use an idempotency key:
POST /payments HTTP/1.1
Idempotency-Key: abc123-unique-request-id
Content-Type: application/json
{"amount": 100, "currency": "USD"}
Server stores the key; subsequent requests with same key return cached response.
API Versioning¶
URI Path Versioning¶
| Pros | Cons |
|---|---|
| Explicit, visible | Not pure REST |
| Easy to implement | URL bloat |
| Easy to cache | Links may break |
Header Versioning¶
| Pros | Cons |
|---|---|
| Clean URLs | Less discoverable |
| RESTful | Harder to test |
Query Parameter¶
| Pros | Cons |
|---|---|
| Easy to test | Not semantic |
| Visible | Can break caching |
Resource Naming¶
Guidelines¶
| Guideline | Good | Bad |
|---|---|---|
| Nouns, not verbs | /orders |
/getOrders |
| Plural | /customers |
/customer |
| Lowercase, kebab-case | /order-items |
/orderItems |
| Hierarchy | /customers/123/orders |
/customerOrders?id=123 |
| No file extensions | /orders/123 |
/orders/123.json |
Collection vs Instance¶
/orders # Collection
/orders/123 # Instance
/orders/123/items # Sub-collection
/orders/123/items/1 # Sub-instance
Pagination¶
Offset-Based¶
| Pros | Cons |
|---|---|
| Simple | Inconsistent with data changes |
| Familiar | Slow for large offsets |
Cursor-Based¶
| Pros | Cons |
|---|---|
| Consistent | Can't jump to page |
| Fast | Opaque cursor |
Filtering, Sorting, Field Selection¶
Filtering¶
Sorting¶
Field Selection¶
Error Responses¶
Use consistent error format:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
},
"request_id": "abc123"
}
| Element | Purpose |
|---|---|
| code | Machine-readable error type |
| message | Human-readable description |
| details | Field-specific errors |
| request_id | Trace for debugging |
Content Negotiation¶
Client specifies desired format:
GET /orders/123 HTTP/1.1
Accept: application/json
Accept-Language: en-US
Accept-Encoding: gzip
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
Content-Encoding: gzip
Best Practices¶
| Practice | Recommendation |
|---|---|
| Use nouns | Resources, not actions |
| Consistent naming | kebab-case, plural |
| HTTP methods | GET, POST, PUT, DELETE semantically |
| Status codes | Correct codes for each situation |
| Versioning | Pick one strategy; stick with it |
| Pagination | Always paginate collections |
| Error format | Consistent across API |
| Documentation | OpenAPI/Swagger |
What is HATEOAS and is it worth implementing?
HATEOAS (Hypermedia as the Engine of Application State) means responses include links to related actions and resources. The client discovers the API by following links. Worth it? Rarely in practice. It adds complexity and most API clients are built against fixed contracts (OpenAPI). Consider it for public APIs where discoverability matters.
PUT vs PATCH — when to use each?
PUT replaces the entire resource — send all fields. Omitted fields may be set to null. PATCH updates specific fields only — send only changed fields. Use PUT when you're replacing; use PATCH for partial updates. PATCH is more bandwidth-efficient but requires clear semantics.
How do you handle API versioning long-term?
(1) Support 2-3 versions max — more is unmanageable. (2) Deprecation policy — announce deprecation 6-12 months ahead. (3) Sunset headers — Sunset: Sat, 31 Dec 2025 23:59:59 GMT. (4) Version in URL is most practical for most teams. (5) Breaking changes require new version; additive changes don't.
📝 Knowledge Check¶
Question 2
PUT vs PATCH on /orders/123 — a client sends {"status": "shipped"}. What should each verb do?
Question 3
Which status codes: (a) async job accepted for processing, (b) request validated but a business rule rejects it, (c) success with no body?
Question 4
A mobile client retries POST /payments on timeout — the server processed the first request but the response was lost. Two charges. What's the fix?