CodingNic
Sign In Book Session

REST API Design

REST Principles

REST API Design 10 min read

REST Principles

Objectives

By the end of this lesson, you should be able to:

  • Explain what makes an API “RESTful” at a conceptual level
  • Identify a resource, and why REST organizes an API around resources rather than actions
  • Explain statelessness, and why it matters for how a client and server communicate

💡 Why this matters: Every route built since Module 5 has technically worked, but “technically works” and “follows conventions another developer immediately understands” are different things. REST is the most common set of those conventions for HTTP APIs.

💡 Note: this lesson is conceptual, establishing vocabulary and principles the rest of this module builds on directly, with real, runnable examples starting in Lesson 2.

What REST Actually Is

REST (Representational State Transfer) is a set of architectural principles for designing networked APIs, not a library, a framework, or a strict specification with a validator, it’s a set of conventions, and different APIs follow them to different degrees. An API described as “RESTful” generally means it organizes itself around resources, exposed at predictable URLs, manipulated through standard HTTP methods, with each request carrying everything the server needs to handle it.

Resources, Not Actions

A REST API is organized around nouns (resources: users, orders, products), not verbs (actions: getUser, createOrder, deleteProduct). Compare:

text
Not RESTful:  GET /getAllUsers
              POST /createNewUser
              POST /deleteUser?id=5

RESTful:      GET /users
              POST /users
              DELETE /users/5

The RESTful version relies on the HTTP method itself (GET, POST, DELETE, covered fully in Lesson 2) to express the action, the URL only ever names the resource. This is a genuine shift in thinking, “what thing am I working with” rather than “what function am I calling,” and it’s what makes a well-designed REST API predictable, once the resource-naming pattern is clear, a client can often guess an endpoint correctly without checking documentation.

Statelessness

Each request to a REST API must carry everything the server needs to understand and fulfill it, the server doesn’t remember anything about a client between requests. A request identifying a user must include that identification itself (a token in a header, covered in a later course’s authentication module), rather than relying on the server having “remembered” who’s asking from an earlier request. This matters practically: a stateless API can be scaled across many server instances freely, any of them can handle any request, since none of them are holding onto client-specific memory the next request would depend on.

Representations

The word “representation” in REST’s full name refers to this: a resource (a user, conceptually) is returned to a client as a representation of that resource, typically JSON (Module 5’s res.json()), the same underlying resource could just as easily be represented as XML or another format, JSON just happens to be the near-universal choice for modern APIs.

Try It

  1. Take three URLs from any API you’ve used or read about (a public API’s documentation is fine), and classify each as resource-oriented (a noun) or action-oriented (a verb).
  2. Rewrite POST /api/deleteOrder?orderId=12 as a resource-oriented, RESTful equivalent.
  3. Explain, in your own words, why a stateless API is easier to scale across multiple servers than one that remembers client-specific information between requests.
  4. Explain, in your own words, the difference between a “resource” and a “representation” of that resource.

Recap

  • REST organizes an API around resources (nouns: /users, /orders), expressed through HTTP methods, rather than actions baked into the URL itself (verbs: /getUsers, /createOrder).
  • Statelessness means every request carries everything the server needs, no memory of a client persists between requests, this is what makes a REST API easy to scale.
  • A resource is returned to a client as a representation, typically JSON, of its current state.

Next lesson: CRUD, mapping create, read, update, and delete to HTTP methods correctly.