Building a REST API with Express

What Makes an API RESTful?

REST (Representational State Transfer) models an API around resources, nouns like users, orders, products, identified by URLs, and manipulated through standard HTTP methods. A RESTful API is stateless: each request carries all the information the server needs, with no server-side session tying requests together.

In Express, this translates directly into resource-based routers: /users for the collection, /users/:id for an individual resource, and the HTTP method (GET, POST, PUT, DELETE) expressing the intended action.

app.get('/users', listUsers);       // read the collection
app.get('/users/:id', getUser);     // read one resource
app.post('/users', createUser);     // create a new resource
app.put('/users/:id', replaceUser); // replace a resource
app.delete('/users/:id', deleteUser);// remove a resource

Notice the URL never contains a verb, getUser or deleteUser, the HTTP method itself carries that meaning.

REST Resource Naming Conventions

/users            (collection)
/users/:id        (single resource)
/users/:id/orders (nested collection)
/users/:id/orders/:orderId (nested resource)

• Use plural nouns for collections (/users, not /user).
• Never put verbs in the URL, let the HTTP method express the action.
• Keep resource identifiers consistent, usually a database ID or slug.
• Nest sub-resources only when they truly belong to a parent (see the Nested Routes lesson).

REST API Cheatsheet

The standard REST mapping of HTTP verbs, paths, and status codes.

Statelessness in Practice

A stateless API does not rely on server-side session data to interpret a request, every request should carry the identity/auth information it needs (typically a bearer token in the Authorization header) rather than depending on a previous request having set server memory.

• Prefer stateless authentication (JWT) over server-side sessions for pure APIs.
• Each request should be understandable in isolation, without server-side history.
• Statelessness makes horizontal scaling far simpler, any server instance can handle any request.

Pragmatic REST vs Strict REST

The original REST specification includes ideas like HATEOAS (responses containing links to related actions), which most real-world APIs skip in practice. "Pragmatic REST", resource-oriented URLs, correct verbs, and predictable JSON, is what the overwhelming majority of production Express APIs actually implement, and it's what this course focuses on.

Common Mistakes

• Putting verbs in URLs, like /getUsers or /deleteUser/5, instead of relying on HTTP methods.
• Using GET requests to change data, breaking caching assumptions and REST semantics.
• Returning 200 OK for every response regardless of what actually happened.
• Designing endpoints around UI screens instead of underlying resources.

Key Takeaways

• REST models an API around resources, identified by URLs and manipulated by HTTP methods.
• Collections use plural nouns; single resources are addressed by ID under that collection.
• APIs should be stateless, each request carries what it needs to be understood on its own.
• Most real-world APIs implement pragmatic REST rather than the full original specification.