🧩 RESTful API Design Principles

What REST Actually Is

REST — Representational State Transfer — is an architectural style, not a protocol or a library. Roy Fielding described it in his 2000 doctoral dissertation to capture the design principles that make the web itself scale. When we build "a REST API," we're borrowing those same principles for machine-to-machine communication.

The core idea is a shift in perspective. Instead of thinking in actions ("get the products", "create an order"), you think in resources — nouns that can be created, read, updated, and deleted using the HTTP methods you already know. The action lives in the method; the noun lives in the URL.

💡 The library-catalog analogy. A REST API is like a library catalog. Each book is a resource. Its call number is the URI that leads you to it. The things you can do — look up, add, replace, remove — map to HTTP methods. A book might come as hardcover, paperback, or e-book, just as a resource can be represented as JSON or XML. And the "see also" cross-references at the back are exactly what HATEOAS links provide.

The Six Constraints

Fielding defined REST through six constraints. Satisfy them and you get a system that is scalable, cacheable, and loosely coupled. (Code-on-demand is optional; the other five are required.)

Resource-Oriented Design

The first design step is identifying your resources — the nouns of your system. For an e-commerce platform, those might be products, orders, customers, reviews, and categories. Resources aren't only database tables; they can also be collections, computed values (a sales report), or even a search result.

Every resource comes in two flavors: the collection (all products) and the item (one specific product). This distinction drives your URL design — collections are plural, items are addressed by an identifier within that collection.

Designing Good URIs

Well-designed URIs are the public face of your API. They should be predictable enough that a developer can guess the next endpoint without reading the docs.

CRUD → HTTP Methods

The four database operations map directly onto HTTP methods against your two URI shapes:

Create (POST) — full request and response

POST /api/products HTTP/1.1
Host: shop.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJ...

{
  "name": "Wireless Headphones",
  "price": 129.99,
  "category": "electronics"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/products/42

{
  "id": 42,
  "name": "Wireless Headphones",
  "price": 129.99,
  "category": "electronics",
  "created_at": "2026-07-31T10:30:00Z"
}

List with paging, filtering, and sorting (GET)

GET /api/products?category=electronics&sort=price&page=1&limit=2 HTTP/1.1
Host: shop.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60

{
  "data": [
    { "id": 42, "name": "Wireless Headphones", "price": 129.99 },
    { "id": 17, "name": "Bluetooth Speaker",  "price": 79.99  }
  ],
  "pagination": { "total": 2, "page": 1, "limit": 2 }
}

Handling Relationships

Real domains are webs of related resources: a user has orders, an order has items, a product belongs to categories. REST offers two ways to express these, and mature APIs mix both.

Approach 1 — Nested resources

GET  /api/users/42/orders        # all orders belonging to user 42
POST /api/users/42/orders        # create an order for user 42
GET  /api/users/42/orders/1007   # a specific order in that context

Nesting clearly expresses ownership and lets you enforce access control at the parent. The downside is depth: /companies/1/departments/3/employees/9/tasks quickly becomes unwieldy.

Approach 2 — Linking with query filters

GET /api/orders?user_id=42       # same data, flatter structure

Linking keeps URLs shallow and is far more flexible for complex queries, at the cost of making the relationship less obvious in the path.

Content Negotiation

The same resource can have multiple representations. Content negotiation lets the client ask for the format (and language) it wants via the Accept and Accept-Language headers — the server picks the best available match and echoes its choice in Content-Type.

GET /api/products/42 HTTP/1.1
Accept: application/json
Accept-Language: fr-FR, en;q=0.8

HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: fr-FR

{ "id": 42, "nom": "Casque sans fil", "prix": 129.99 }

Here's how you'd honor the Accept header in Express:

app.get('/api/products/:id', (req, res) => {
  const product = db.get(req.params.id);
  if (!product) return res.status(404).json({ code: 'NOT_FOUND' });

  res.format({
    'application/json': () => res.json(product),
    'application/xml':  () => res.type('application/xml').send(toXml(product)),
    default:            () => res.json(product) // sensible fallback
  });
});

HATEOAS & API Evolution

HATEOAS — Hypermedia As The Engine Of Application State — is the most overlooked REST constraint. The idea: responses include links that tell the client what it can do next, so the client discovers the API as it goes instead of hard-coding every URL.

It works exactly like browsing a website: you don't memorize every URL, you follow links from page to page. A HATEOAS response does the same for a machine client.

Without HATEOAS — the client must already know every URL

{
  "id": "1007",
  "total": 99.99,
  "status": "shipped",
  "customer_id": "42"
}

With HATEOAS — the response is self-describing

{
  "id": "1007",
  "total": 99.99,
  "status": "shipped",
  "_links": {
    "self":     { "href": "/api/orders/1007" },
    "customer": { "href": "/api/customers/42" },
    "items":    { "href": "/api/orders/1007/items" },
    "return":   { "href": "/api/orders/1007/return", "method": "POST" }
  }
}

Notice the return link appears only because the order is shipped. State-appropriate links mean the server can guide the client through valid actions — and can add or move endpoints later without breaking clients that follow links instead of building URLs by hand.

Hands-on Exercise

GET    /books                 # list/search books (?author=, ?available=true)
GET    /books/5               # one book
POST   /loans                 # check out a book
DELETE /loans/900             # return a book (or PATCH status)
GET    /patrons/42/loans      # a patron's current loans

POST /loans
{ "book_id": 5, "patron_id": 42 }

--> 201 Created
    Location: /loans/900
    { "id": 900, "book_id": 5, "patron_id": 42, "due": "2026-08-14" }

--> 409 Conflict   (if the book is already on loan)
    { "code": "BOOK_UNAVAILABLE", "message": "That book is checked out." }

Summary & Quiz

📚 Further Reading

• Roy Fielding — REST APIs must be hypertext-driven
• JSON:API — a conventions specification
• MDN — HTTP content negotiation
• Best Practices for a Pragmatic RESTful API

🚀 What's Next?

You can now design a well-structured API. Next, API Design Best Practices polishes it: consistent error formats, versioning strategies, documentation with OpenAPI, authentication choices, caching, and performance.