🌐 REST Principles

What Is REST?

REST stands for Representational State Transfer. It is not a protocol, a library, or a standard you install — it is an architectural style: a set of constraints that, when you follow them, produce web APIs that are simple, scalable, and durable. Roy Fielding described it in his year-2000 doctoral dissertation, essentially writing down the design principles that already made the web itself work so well.

An API that follows these constraints is called RESTful. The core idea is disarmingly simple: model everything in your system as a resource (a user, an order, a photo), give each resource a URL, and manipulate it with the standard HTTP methods the web already speaks.

Because REST rides on plain HTTP, it works with every browser, every programming language, every proxy and cache on the internet — no special tooling required. That universality is a big part of why REST beat heavier alternatives like SOAP for public web APIs.

The Six REST Constraints

Fielding defined REST through six constraints. Five are required; one (code-on-demand) is optional. Each constraint trades a little freedom for a lot of predictability.

The Uniform Interface — the heart of REST

Of the six, the uniform interface is what makes REST feel like REST. It has four sub-rules:

• Identification of resources — each resource has a stable URL, e.g. /users/123.
• Manipulation through representations — the client works with a JSON (or XML) representation of the resource, not the resource itself.
• Self-descriptive messages — each message carries enough metadata (method, headers, media type) to be understood on its own.
• HATEOAS — Hypermedia As The Engine Of Application State: responses include links telling the client what it can do next.

Statelessness in Depth

Statelessness is the constraint people misunderstand most, so let's slow down. Stateless means the server keeps no memory of previous requests between calls. Every request must carry all the context needed to process it — most importantly, who you are.

Compare two ways to remember a logged-in user:

# ❌ Stateful: the server stores a session in memory, keyed by a cookie.
# Request 2 only works if it lands on the SAME server that handled login.
GET /api/orders HTTP/1.1
Cookie: sessionId=abc123        # server must look this up in its own memory

# ✅ Stateless: the request carries a self-contained token every time.
# ANY server instance can verify it — no shared memory required.
GET /api/orders HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...

Why does this unlock scaling? If the server remembers nothing, then request #1 and request #2 can be handled by different machines. You put a load balancer in front of ten identical servers, and it can send each request wherever there's capacity. Need more throughput? Add an eleventh server. This is horizontal scaling, and statelessness is what makes it painless.

Resources: Nouns, Not Verbs

The single most important design habit in REST: URLs name things, HTTP methods do things. A URL should be a noun — a resource — and the verb comes from the method. The moment you see a verb in a path, something has gone wrong.

Collections and members

Two URL shapes cover almost everything:

• A collection — plural noun: /users, /products, /orders.
• A member of that collection — collection plus an identifier: /users/123.

Resources relate to one another, and hierarchy shows that relationship:

GET /posts                      # all blog posts
GET /posts/42                   # one specific post
GET /posts/42/comments          # all comments ON post 42
GET /posts/42/comments/7        # comment 7 on post 42
GET /users/9/posts              # all posts BY user 9

HTTP Methods & CRUD

REST maps the four classic data operations — Create, Read, Update, Delete — onto HTTP methods. Because the method carries the intent, the same URL can serve several operations.

Two properties worth memorizing: safe and idempotent

• Safe — the request does not change server state. It's read-only. Only GET and HEAD are safe.
• Idempotent — making the same request many times has the same effect as making it once. GET, PUT, and DELETE are idempotent; POST is not.

Here is the mapping expressed in Express, the Node.js framework you'll use all week:

const express = require('express');
const app = express();
app.use(express.json());          // parse JSON request bodies

// READ the whole collection
app.get('/users', (req, res) => {
  res.status(200).json(getAllUsers());
});

// READ one member
app.get('/users/:id', (req, res) => {
  const user = getUserById(req.params.id);
  if (!user) return res.status(404).json({ error: 'Not Found' });
  res.status(200).json(user);
});

// CREATE — POST to the collection, respond 201 + Location header
app.post('/users', (req, res) => {
  const user = createUser(req.body);
  res.status(201).location(`/users/${user.id}`).json(user);
});

// REPLACE the whole member
app.put('/users/:id', (req, res) => {
  const user = replaceUser(req.params.id, req.body);
  res.status(200).json(user);
});

// PARTIAL update
app.patch('/users/:id', (req, res) => {
  const user = updateUser(req.params.id, req.body);
  res.status(200).json(user);
});

// DELETE — 204 means "success, nothing to return"
app.delete('/users/:id', (req, res) => {
  deleteUser(req.params.id);
  res.status(204).end();
});

Notice the shape: the same URLs, different methods. That uniformity is the payoff of following the constraints. (The exact status codes get a lesson of their own — that's next.)

The Richardson Maturity Model

Not every "REST API" is equally RESTful. Leonard Richardson proposed a four-level scale (popularized by Martin Fowler) that measures how fully an API embraces the constraints. It's a handy way to grade your own designs.

• Level 0 — The Swamp of POX. A single endpoint, everything is POST, the body says what to do. This is remote-procedure-call dressed up as HTTP.
• Level 1 — Resources. You introduce many URLs (/users, /orders) but still lean on one method.
• Level 2 — HTTP Verbs. You use GET/POST/PUT/DELETE correctly and return meaningful status codes. Most production APIs live here — and that's perfectly respectable.
• Level 3 — Hypermedia (HATEOAS). Responses include links to related resources and available actions, so clients discover the API by following links rather than hard-coding URLs.

// A Level 3 response embeds links telling the client what it can do next
{
  "id": 123,
  "name": "Ada Lovelace",
  "status": "active",
  "_links": {
    "self":       { "href": "/users/123" },
    "orders":     { "href": "/users/123/orders" },
    "deactivate": { "href": "/users/123/deactivate", "method": "POST" }
  }
}

Practice & Quiz

POST /getAllProducts
POST /getProductById?id=88
POST /addProduct
POST /editProduct?id=88
POST /removeProduct?id=88
POST /getReviewsForProduct?id=88

GET    /products              # was getAllProducts
GET    /products/88           # was getProductById?id=88
POST   /products              # was addProduct
PUT    /products/88           # was editProduct (or PATCH for a partial edit)
DELETE /products/88           # was removeProduct
GET    /products/88/reviews   # was getReviewsForProduct?id=88

GET /authors                    # all authors
GET /authors/12                 # one author
GET /authors/12/books           # books BY author 12
GET /books                      # all books
GET /books/500                  # one book
GET /books/500/reviews          # reviews OF book 500
GET /reviews/9                  # a review, directly (flattened access)

Best Practices & Pitfalls

✅ Do

• Name resources with plural nouns and let HTTP methods supply the verbs
• Keep the server stateless — send auth on every request (token, not server session)
• Use consistent conventions across the whole API (casing, pluralization, error shape)
• Limit URL nesting to 2–3 levels; flatten deep relationships
• Match methods to CRUD and respect safe/idempotent semantics

❌ Don't

• Put verbs in paths (/createUser, /deleteOrder)
• Use GET for anything that changes data — it must stay safe
• Store per-user conversation state in server memory between requests
• Mix singular and plural (/user here, /orders there)
• Assume "uses JSON over HTTP" automatically means "RESTful" — check it against the constraints

# These are HTTP + JSON, but NOT RESTful — they're RPC in disguise:
POST /api/doLogin
POST /api/fetchUserData
POST /api/updateEverything

Summary

📚 Additional Resources

• restfulapi.net — REST API Tutorial
• MDN — An overview of HTTP
• Martin Fowler — The Richardson Maturity Model
• Roy Fielding — Architectural Styles (the original REST chapter)

🚀 What's Next?

You know the philosophy; next you get precise about the vocabulary. The following lesson, HTTP Methods & Status Codes, digs into each method's exact semantics and the full set of response codes — 200, 201, 204, 400, 401, 403, 404, 409, 422, 500 — so your API always says exactly what happened.