REST API Design Made Simple with Express.js

When a mobile app loads your profile, when a website fetches a list of products, when a dashboard displays live data, something is making requests to a server and receiving structured responses back.

That communication happens through an API, and the most common way to design one is REST.

REST is not a protocol or a library.

It is a set of conventions for how an API should be structured.

Follow those conventions and you end up with an API that other developers can understand, predict, and work with confidently, even if they have never seen your code before.

* * *

What REST Means

REST stands for Representational State Transfer.

Underneath the formal name is a practical idea: your API should be organized around resources, and clients interact with those resources using standard HTTP methods.

A resource is any meaningful piece of data your application manages.

Users, products, orders, articles, comments: these are all resources.

In a REST API,

each resource has its own URL, and you interact with it using the same HTTP methods the web already understands.

The communication works like this.

A client, a browser, a mobile app, another server, sends an HTTP request to a URL with a method.

The server processes the request, does whatever needs doing, and sends back a response with a status code and usually some data.

The client reads the response and knows whether things went well or not.

Both sides speak the same language.

The client does not need to know how the server is built.

The server does not need to know what kind of client is making the request.

They agree on the structure of the conversation, and that agreement is what REST defines.

* * *

Resources and URLs

In REST, URLs represent resources, not actions.

This is one of the most important conventions and the one most often violated in practice.

A URL should describe what you are working with, not what you are doing to it:

1Good: /users
2Good: /users/42
3Good: /users/42/posts
4
5Not ideal: /getUsers
6Not ideal: /createUser
7Not ideal: /deleteUserById

The action is expressed through the HTTP method, not the URL. /users with a GET means fetch users. /users with a POST means create a user.

Same URL, different method, different meaning.

This keeps your URLs clean and your API predictable.

Resources in URLs are almost always plural nouns. /users not /user. /products not /product.

Individual items within a collection are addressed by their identifier: /users/42 refers to the user with ID 42.

* * *

HTTP Methods

HTTP provides several methods, and REST assigns a clear meaning to each one.

Four of them cover the vast majority of what any API needs to do.

GET retrieves data.

It should never modify anything.

When a client sends a GET request, they are asking to read a resource.

The server returns it.

Nothing on the server changes.

POST creates something new.

The client sends data in the request body, and the server uses it to create a new resource.

The response typically includes the created resource or at least its identifier.

PUT updates an existing resource.

The client sends the full updated version of the resource, and the server replaces what it has stored.

If any fields are missing from the request, they are typically cleared or reset.

DELETE removes a resource.

The client identifies what to remove through the URL, and the server deletes it.

There is usually no request body.

These four methods map naturally to the four basic operations data needs to support: create, read, update, and delete.

* * *

Status Codes

The status code in a response tells the client immediately whether the request succeeded, failed, or something else happened.

They are grouped by the first digit.

Codes in the 200 range mean success. 200 OK is the standard success response for GET and PUT requests.

201 Created signals that a POST request succeeded and a new resource was created.

204 No Content is used for successful DELETE requests where there is nothing to return.

Codes in the 400 range mean the client made an error.

400 Bad Request means the request was malformed or missing required data.

401 Unauthorized means authentication is required.

403 Forbidden means the client is authenticated but not allowed to do what they are asking.

404 Not Found means the resource does not exist.

Codes in the 500 range mean something went wrong on the server.

500 Internal Server Error is the generic catch-all for unexpected failures.

Returning accurate status codes is part of what makes an API genuinely useful.

A client that receives a 404

knows the resource does not exist.

A client that receives a 401 knows it needs to authenticate.

These are meaningful signals that the client can act on.

* * *

Designing Routes for a Users Resource

With these conventions in place, designing the routes for a users resource follows a consistent pattern.

The same pattern applies to any resource in your API.

| Method | URL | Action | | --- | --- | --- | | GET | /users | Return all users | | POST | /users | Create a new user | | GET | /users/:id | Return one user | | PUT | /users/:id | Update one user | | DELETE | /users/:id | Delete one user |

Two URLs, five routes.

The collection URL handles listing and creating.

The individual item URL handles reading, updating, and deleting a specific resource.

This structure is predictable enough that a developer who has never seen your API can make an educated guess about how it works.

* * *

Building the Routes in Express

Setting up these routes in Express is straightforward.

Each route receives a handler that reads from the request, interacts with whatever data store you are using, and sends back an appropriate response.

1const express = require("express");
2const app = express();
3
4app.use(express.json());
5
6const users = [
7  { id: 1, name: "Shivam", email: "shivam@example.com" },
8  { id: 2, name: "Loid", email: "loid@example.com" }
9];
10
11let nextId = 3;

A simple in-memory array stands in for a real database here.

The logic that follows would work identically with a database call in place of the array operations.

GET /users: return all users

1app.get("/users", (req, res) => {
2  res.status(200).json(users);
3});

Returns the entire collection.

Status 200 signals success.

POST /users: create a new user

1app.post("/users", (req, res) => {
2  const { name, email } = req.body;
3
4  if (!name || !email) {
5    return res.status(400).json({ error: "Name and email are required" });
6  }
7
8  const newUser = { id: nextId++, name, email };
9  users.push(newUser);
10
11  res.status(201).json(newUser);
12});

Validates that required fields are present.

Returns 400 with a clear message if they are not.

Creates the user and returns 201 with the newly created resource.

GET /users/:id: return one user

1app.get("/users/:id", (req, res) => {
2  const user = users.find(u => u.id === parseInt(req.params.id));
3
4  if (!user) {
5    return res.status(404).json({ error: "User not found" });
6  }
7
8  res.status(200).json(user);
9});

Parses the ID from the URL, finds the matching user, returns 404 if none exists, and returns 200 with the user if found.

PUT /users/:id: update one user

1app.put("/users/:id", (req, res) => {
2  const index = users.findIndex(u => u.id === parseInt(req.params.id));
3
4  if (index === -1) {
5    return res.status(404).json({ error: "User not found" });
6  }
7
8  const { name, email } = req.body;
9
10  if (!name || !email) {
11    return res.status(400).json({ error: "Name and email are required" });
12  }
13
14  users[index] = { id: users[index].id, name, email };
15
16  res.status(200).json(users[index]);
17});

Finds the user by ID, replaces their data with what was sent in the request body, and returns the updated user.

The ID is preserved from the original record rather than taken from the request body.

DELETE /users/:id: delete one user

1app.delete("/users/:id", (req, res) => {
2  const index = users.findIndex(u => u.id === parseInt(req.params.id));
3
4  if (index === -1) {
5    return res.status(404).json({ error: "User not found" });
6  }
7
8  users.splice(index, 1);
9
10  res.status(204).send();
11});

Removes the user from the array and returns 204 with no body.

There is nothing to return after a deletion, and 204 signals that explicitly.

* * *

Consistent Response Shape

One practice that makes an API significantly easier to work with is keeping response shapes consistent.

When every endpoint returns data in a predictable structure, the client knows what to expect regardless of which route it is calling.

A common pattern wraps data in a consistent envelope:

1res.status(200).json({
2  success: true,
3  data: user
4});
5
6res.status(400).json({
7  success: false,
8  error: "Name and email are required"
9});

Success responses always have success: true and a data field.

Error responses always have success: false and an error field.

A client can check success first and branch accordingly, without writing different parsing logic for every endpoint.

* * *

Wrapping Up

REST API design comes down to a few consistent conventions applied repeatedly:

resources have URLs, actions are expressed through

HTTP methods, responses carry meaningful status codes,

and the structure stays predictable across every endpoint.

A developer seeing your /users routes for the first time

already knows what GET, POST, PUT, and DELETE do on those URLs.

They know what a 201 response means and what to check when they get a 404.

That shared understanding is what makes REST valuable, and Express makes it straightforward to implement cleanly.

The users example here is deliberately simple.

The same pattern scales directly to any resource: posts, products, orders, comments.

Apply the same URL conventions, the same method semantics, and the same status codes, and the API stays coherent as it grows.

Thank you for reading 💖