REST Fundamentals

1What REST Actually Is

REST (Representational State Transfer) is not a protocol, a library, or a file format — it is an architectural style defined by Roy Fielding in his 2000 doctoral dissertation. It describes a set of constraints that, when applied together to a client-server system built on HTTP, produce specific properties: scalability, a uniform interface, independent evolution of client and server, and cacheability.

"REST API" is shorthand for "an HTTP API that follows (most of) these constraints." Plenty of APIs are called "REST" while only loosely following the style — this topic covers what the style actually requires versus what has become colloquial usage.

GET    /v1/pets/77              → read one pet
GET    /v1/owners/12/pets       → list an owner's pets
POST   /v1/orders               → create an order
DELETE /v1/orders/482           → cancel/delete an order

2The Six Constraints

3The Uniform Interface — Four Sub-Constraints

The uniform interface is what makes REST "REST" rather than just "an HTTP API." It has four parts:

1. Identification of resources — every piece of information the API exposes (a user, an order, a collection of orders) is a resource, addressed by a stable URI (/orders/482).
2. Manipulation of resources through representations — a client never touches the resource directly; it exchanges representations of it (a JSON document, typically) and the server translates between representation and internal state.
3. Self-descriptive messages — each message includes enough information to describe how to process it: a Content-Type header telling the client/server how to parse the body, standard HTTP methods and status codes carrying well-known semantics.
4. HATEOAS (Hypermedia As The Engine Of Application State) — responses include links describing what the client can do next, so clients aren't hard-coded with URI structure. This is the most-skipped constraint in real-world "REST" APIs.

4Resource vs. Representation

A resource is the concept (the order with id 482). A representation is the serialized snapshot of that concept sent over the wire at a point in time.

GET /orders/482 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "a1b2c3"

{
  "id": 482,
  "status": "shipped",
  "total": 129.99,
  "items": [
    { "sku": "SKU-100", "qty": 2 }
  ]
}

Same resource, different representation is entirely possible — the same order could be returned as XML, HAL+JSON, or a PDF invoice depending on Accept negotiation, without the underlying resource changing.

GET /orders/482
Accept: application/json      → { "id": 482, "status": "shipped", ... }

GET /orders/482
Accept: application/pdf       → %PDF-1.7 … (an invoice document)

5HATEOAS in Practice

A HATEOAS-compliant response embeds the actions available on the current resource as links, rather than the client hard-coding URL patterns:

{
  "id": 482,
  "status": "shipped",
  "total": 129.99,
  "_links": {
    "self": { "href": "/orders/482" },
    "cancel": { "href": "/orders/482/cancel", "method": "POST" },
    "invoice": { "href": "/orders/482/invoice" }
  }
}

If status were "cancelled" instead, the cancel link would simply be absent — the client discovers valid transitions from the response itself instead of encoding business rules like "you can only cancel a shipped order" on the client side.

6The Richardson Maturity Model

Leonard Richardson's maturity model is a practical way to grade how "REST-ful" an API actually is, in four levels (0-3):

7REST vs. RPC vs. SOAP (Quick Contrast)

GET /orders/482 HTTP/1.1
If-None-Match: "a1b2c3"

HTTP/1.1 304 Not Modified

⚠️ Common Pitfalls

1. Calling any JSON-over-HTTP API "REST" — an API with a single /api endpoint that dispatches on an action field in the body (Richardson level 0) is RPC, not REST, regardless of what it's marketed as.
2. Confusing "stateless" with "no persisted data" — statelessness is about the server not holding session/conversation state between requests, not about whether the server has a database. The order itself (persisted state) is completely fine; a server-side "current step in a multi-request wizard" is not.
3. Skipping HATEOAS and calling it a REST API anyway — this is extremely common (most "REST APIs" are actually Richardson Level 2), and it's a reasonable pragmatic choice, but it's worth knowing you've made that trade-off rather than believing you've implemented "true REST."
4. Treating the URI as an implementation detail the client should parse — e.g. clients constructing /orders/${id}/cancel themselves by string concatenation instead of following a cancel link from the resource — reintroduces tight coupling REST was designed to avoid.
5. Assuming REST mandates JSON — REST is representation-agnostic; JSON just won because it's convenient, not because the style requires it.

POST /api
{ "action": "cancelOrder", "id": 482 }

200 OK
{ "ok": false, "error": "not found" }

POST /orders/482/cancel     (a link from the order)

404 Not Found
Content-Type: application/problem+json
{ "title": "Order not found" }

📋 Quick Reference

6 constraints: client-server, stateless, cacheable, uniform interface, layered system, code-on-demand (optional)
Uniform interface: resource identification, representations, self-descriptive messages, HATEOAS
Richardson Maturity Model: 0 (RPC-over-HTTP) -> 1 (resources) -> 2 (HTTP verbs) -> 3 (hypermedia/HATEOAS)
Cacheability mechanics: Cache-Control (freshness) + ETag/If-None-Match (validation, 304 Not Modified)
Most "REST APIs" in the wild = Richardson Level 2 (resources + verbs, no HATEOAS)

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: api_rest_fundamentals_theory.md · generated by tools/build_lessons.py