REST Architecture Constraints and the Richardson Maturity Model

"RESTful" is used loosely – often it just means "JSON over HTTP". Strictly, REST is a set of constraints: rules an architecture follows to get scalability, simplicity and evolvability. Knowing them helps you make better design decisions and answer a very common interview question properly.

The six constraints

Statelessness in practice

Stateless means the server keeps no client session between requests – not that the application has no state. Data lives in the database; who the user is travels with every request:

# stateless: every request identifies itself
GET /api/cart HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

# not RESTful: the server must remember what "next" means for this client
GET /api/orders/next-page HTTP/1.1

The Richardson Maturity Model

Leonard Richardson described four levels of "how RESTful" an HTTP API is:

# Level 0                                  # Level 2
POST /api  {"action": "getOrder", "id": 7} GET    /api/orders/7
POST /api  {"action": "cancelOrder", …}    DELETE /api/orders/7

HATEOAS: links in responses

Hypermedia As The Engine Of Application State means a response tells the client what it can do next, through links – like a web page's links tell you where you can go. The client follows links instead of hard-coding every URL:

// server.js
import express from 'express';

const app = express();
const orders = { 7: { id: 7, status: 'pending', total: 1499 }, 8: { id: 8, status: 'shipped', total: 899 } };

function withLinks(order) {
  const self = `/api/orders/${order.id}`;
  const links = { self: { href: self }, items: { href: `${self}/items` } };
  if (order.status === 'pending') {
    links.pay = { href: `${self}/payment`, method: 'POST' };       // only offered while pending
    links.cancel = { href: self, method: 'DELETE' };
  }
  if (order.status === 'shipped') {
    links.track = { href: `${self}/tracking` };
  }
  return { ...order, _links: links };
}

app.get('/api/orders/:id', (req, res) => {
  const order = orders[req.params.id];
  if (!order) return res.status(404).json({ error: 'Order not found' });
  res.json(withLinks(order));
});

app.listen(process.env.PORT ?? 3000);

$ curl http://localhost:3000/api/orders/7
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": 7,
  "status": "pending",
  "total": 1499,
  "_links": {
    "self": {
      "href": "/api/orders/7"
    },
    "items": {
      "href": "/api/orders/7/items"
    },
    "pay": {
      "href": "/api/orders/7/payment",
      "method": "POST"
    },
    "cancel": {
      "href": "/api/orders/7",
      "method": "DELETE"
    }
  }
}

$ curl http://localhost:3000/api/orders/8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": 8,
  "status": "shipped",
  "total": 899,
  "_links": {
    "self": {
      "href": "/api/orders/8"
    },
    "items": {
      "href": "/api/orders/8/items"
    },
    "track": {
      "href": "/api/orders/8/tracking"
    }
  }
}

The pending order offers pay and cancel; the shipped one offers track instead. The server – not every client – owns the rules about what's allowed. Formats such as HAL (the _links style used here) and JSON:API standardise this. In practice, many production APIs stop at Level 2, but links for pagination and related resources are common and very useful.

Practice

Summary