REST API Design Made Simple with Express.js

"An API is a contract between your server and everyone who wants to talk to it. REST is the language that contract is written in."

Introduction

Every time your frontend fetches a list of users, a mobile app submits a form, or one service talks to another — that communication happens through an API. And the most widely adopted style for building those APIs is REST.

REST isn't a library or a framework. It's a set of conventions — a shared language for structuring how clients and servers communicate. Express.js is the tool that makes implementing those conventions in Node.js clean and fast.

By the end of this guide you'll understand what REST means, how HTTP methods map to actions, how to name your routes correctly, and how to build a complete set of user endpoints with Express.

1. What REST API Means

REST stands for Representational State Transfer. Ignore the academic name — what it actually means in practice is a simple set of rules for how a client (a browser, a mobile app, another server) communicates with your server over HTTP.

APIs as Communication

Think of an API as a waiter in a restaurant:

CLIENT                        SERVER
(diner)                    (kitchen)

  │  "I'd like the user     │
  │   with ID 42, please"   │
  │ ──────────────────────► │
  │                         │  looks up user 42
  │                         │  prepares a response
  │ ◄────────────────────── │
  │  Here's your user:      │
  │  { id: 42, name: "..." }│

The client doesn't know how the kitchen works. It just sends a request in the right format and expects a response. The API is the menu that defines what requests are valid and what responses look like.

What Makes an API "RESTful"

A REST API follows these core principles:

Resources over actions — You describe things (users, orders, products), not verbs (getUser, createOrder). The action is expressed by the HTTP method, not the URL.

Stateless — Every request contains all the information the server needs. The server holds no session between requests.

Uniform interface — Consistent URL patterns and HTTP methods mean any developer can predict how your API works without reading every endpoint's documentation.

2. Resources in REST Architecture

The most important concept in REST is the resource. A resource is any piece of data your API exposes — a user, a post, a product, an order.

In REST, resources are represented as nouns in the URL:

✅ CORRECT — noun-based resources
/users
/users/42
/users/42/posts

❌ WRONG — verb-based URLs (not RESTful)
/getUser
/createUser
/deleteUserById
/fetchAllPosts

The URL tells you what you're working with. The HTTP method tells you what you want to do with it.

Two URL Patterns

Every resource has two URL patterns:

COLLECTION       →  /users         (all users)
SINGLE RESOURCE  →  /users/:id     (one specific user)

This simple pattern covers every operation you'll ever need.

3. HTTP Methods: The Four Pillars of REST

HTTP methods are the verbs that act on your noun-based resources. Four cover the overwhelming majority of what any API needs to do.

HTTP METHOD  │  ACTION        │  SQL EQUIVALENT  │  CRUD
─────────────┼────────────────┼──────────────────┼────────
GET          │  Read          │  SELECT           │  Read
POST         │  Create        │  INSERT           │  Create
PUT          │  Update        │  UPDATE           │  Update
DELETE       │  Remove        │  DELETE           │  Delete

GET — Fetch Data

GET retrieves data. It should never change anything on the server. It's safe to call multiple times with the same result.

// Get all users
app.get("/users", async (req, res) => {
  const users = await db.getAll();
  res.status(200).json(users);
});

// Get a specific user
app.get("/users/:id", async (req, res) => {
  const user = await db.getById(req.params.id);
  res.status(200).json(user);
});

POST — Create a Resource

POST creates a new resource. The data for the new resource comes in the request body. The server decides the new resource's ID.

// Create a new user
app.post("/users", async (req, res) => {
  const { name, email } = req.body;
  const newUser = await db.create({ name, email });
  res.status(201).json(newUser); // 201 = Created
});

PUT — Update a Resource

PUT updates an existing resource. It typically replaces the entire resource with the new data sent in the body.

// Update (replace) a user
app.put("/users/:id", async (req, res) => {
  const { name, email } = req.body;
  const updatedUser = await db.update(req.params.id, { name, email });
  res.status(200).json(updatedUser);
});

PUT vs PATCH: PUT replaces the whole resource. PATCH updates only the fields you send. For simplicity, most beginner APIs just use PUT.

DELETE — Remove a Resource

DELETE removes a resource. The server deletes it and typically responds with either the deleted item or nothing (just a status code).

// Delete a user
app.delete("/users/:id", async (req, res) => {
  await db.delete(req.params.id);
  res.status(204).send(); // 204 = No Content (success, nothing to return)
});

4. Status Codes: Communicating What Happened

HTTP status codes are the server's way of telling the client what happened to its request. They're three-digit numbers grouped by category.

The Categories

1xx → Informational   (rare in APIs)
2xx → Success         (request worked)
3xx → Redirection     (go look elsewhere)
4xx → Client error    (you did something wrong)
5xx → Server error    (we did something wrong)

The Codes You'll Actually Use

Code	Name	When to use
`200`	OK	Successful GET, PUT
`201`	Created	Successful POST — new resource made
`204`	No Content	Success, nothing to return (DELETE)
`400`	Bad Request	Request body is malformed or missing fields
`401`	Unauthorized	No valid authentication provided
`403`	Forbidden	Authenticated, but not allowed to do this
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Resource already exists (duplicate email)
`500`	Internal Server Error	Something broke on the server

In Practice

app.get("/users/:id", async (req, res) => {
  const user = await db.getById(req.params.id);

  if (!user) {
    return res.status(404).json({ error: "User not found" });
    //                   ^^^  Tell the client WHY it failed
  }

  res.status(200).json(user);
});

The key rule: Never just send 200 with an error message in the body. Use the actual status code — that's how clients (and developers) know what happened without reading the response body.

5. Designing REST Routes

Good REST route design is consistent, predictable, and readable. Here are the conventions that make routes instantly understandable.

URL Convention Rules

RULE 1 — Always use plural nouns
  ✅  /users      ❌  /user
  ✅  /products   ❌  /product

RULE 2 — Use kebab-case for multi-word resources
  ✅  /blog-posts   ❌  /blogPosts   ❌  /blog_posts

RULE 3 — No verbs in URLs (the method IS the verb)
  ✅  DELETE /users/42       ❌  POST /deleteUser/42
  ✅  POST   /users          ❌  GET  /createUser

RULE 4 — Nest for sub-resources (but max 2 levels deep)
  ✅  /users/42/posts         (posts belonging to user 42)
  ✅  /users/42/posts/7       (post 7 belonging to user 42)
  ❌  /users/42/posts/7/comments/3/likes   (too deep)

RULE 5 — Query strings for filtering, sorting, pagination
  ✅  GET /users?role=admin
  ✅  GET /users?sort=createdAt&order=desc
  ✅  GET /users?page=2&limit=20

The Request-Response Lifecycle

CLIENT                                           SERVER
  │                                                │
  │   GET /users/42                                │
  │   Headers: { Authorization: "Bearer ..." }     │
  │ ─────────────────────────────────────────────► │
  │                                                │  1. Parse URL → extract id: 42
  │                                                │  2. Run middleware (auth check)
  │                                                │  3. Hit route handler
  │                                                │  4. Query database
  │                                                │  5. Build response
  │                                                │
  │ ◄───────────────────────────────────────────── │
  │   Status: 200 OK                               │
  │   Content-Type: application/json               │
  │   Body: { "id": 42, "name": "Alice", ... }     │
  │                                                │
  │   (or on failure)                              │
  │                                                │
  │ ◄───────────────────────────────────────────── │
  │   Status: 404 Not Found                        │
  │   Body: { "error": "User not found" }          │

6. Example Resource: Users

Let's bring everything together and build a complete, RESTful users API with Express.

The Route Map

METHOD   ROUTE           ACTION               BODY REQUIRED?
──────────────────────────────────────────────────────────
GET      /users          List all users        No
GET      /users/:id      Get one user          No
POST     /users          Create a user         Yes
PUT      /users/:id      Update a user         Yes
DELETE   /users/:id      Delete a user         No

The Full Implementation

const express = require("express");
const app = express();

// Parse incoming JSON bodies
app.use(express.json());

// ── In-memory data store (replace with a real DB) ─────────
let users = [
  { id: 1, name: "Alice", email: "alice@example.com", role: "admin"  },
  { id: 2, name: "Bob",   email: "bob@example.com",   role: "editor" },
  { id: 3, name: "Carol", email: "carol@example.com", role: "viewer" }
];
let nextId = 4;

// ── GET /users ────────────────────────────────────────────
app.get("/users", (req, res) => {
  let result = users;
  if (req.query.role) {
    result = users.filter(u => u.role === req.query.role);
  }
  res.status(200).json(result);
});

// ── GET /users/:id ────────────────────────────────────────
app.get("/users/:id", (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: "User not found" });
  res.status(200).json(user);
});

// ── POST /users ───────────────────────────────────────────
app.post("/users", (req, res) => {
  const { name, email, role } = req.body;

  if (!name || !email) {
    return res.status(400).json({ error: "Name and email are required" });
  }

  const exists = users.find(u => u.email === email);
  if (exists) {
    return res.status(409).json({ error: "Email already in use" });
  }

  const newUser = { id: nextId++, name, email, role: role || "viewer" };
  users.push(newUser);
  res.status(201).json(newUser);
});

// ── PUT /users/:id ────────────────────────────────────────
app.put("/users/:id", (req, res) => {
  const index = users.findIndex(u => u.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: "User not found" });

  const { name, email, role } = req.body;
  if (!name || !email) {
    return res.status(400).json({ error: "Name and email are required" });
  }

  users[index] = { id: users[index].id, name, email, role: role || users[index].role };
  res.status(200).json(users[index]);
});

// ── DELETE /users/:id ─────────────────────────────────────
app.delete("/users/:id", (req, res) => {
  const index = users.findIndex(u => u.id === parseInt(req.params.id));
  if (index === -1) return res.status(404).json({ error: "User not found" });
  users.splice(index, 1);
  res.status(204).send();
});

app.listen(3000, () => console.log("API running at http://localhost:3000"));

Testing with curl

# List all users
curl http://localhost:3000/users

# Filter by role
curl "http://localhost:3000/users?role=admin"

# Get one user
curl http://localhost:3000/users/1

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Dave","email":"dave@example.com","role":"editor"}'

# Update a user
curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice Smith","email":"alice@example.com","role":"admin"}'

# Delete a user
curl -X DELETE http://localhost:3000/users/2

What Each Response Looks Like

GET /users           → 200  [ { id, name, email, role }, ... ]
GET /users/1         → 200  { id: 1, name: "Alice", ... }
GET /users/999       → 404  { error: "User not found" }
POST /users          → 201  { id: 4, name: "Dave", ... }
POST /users (no email) → 400  { error: "Name and email are required" }
POST /users (dupe)   → 409  { error: "Email already in use" }
PUT /users/1         → 200  { id: 1, name: "Alice Smith", ... }
DELETE /users/2      → 204  (empty body)

CRUD → HTTP Method Mapping

ACTION      │  METHOD  │  ROUTE        │  SUCCESS CODE
────────────┼──────────┼───────────────┼──────────────
Read all    │  GET     │  /users       │  200 OK
Read one    │  GET     │  /users/:id   │  200 OK
Create      │  POST    │  /users       │  201 Created
Update      │  PUT     │  /users/:id   │  200 OK
Delete      │  DELETE  │  /users/:id   │  204 No Content
────────────┼──────────┼───────────────┼──────────────
Not found   │  any     │  /users/:id   │  404 Not Found
Bad body    │  POST/PUT│  /users       │  400 Bad Request
Duplicate   │  POST    │  /users       │  409 Conflict

Quick Reference

Concept	Rule
URL naming	Plural nouns: `/users`, `/products`
Multi-word	Kebab-case: `/blog-posts`
No verbs in URLs	The HTTP method is the verb
Sub-resources	Nest up to 2 levels: `/users/:id/posts`
Filtering / paging	Query strings: `?role=admin&page=2`
Successful GET	`200 OK` + data
Successful POST	`201 Created` + new resource
Successful DELETE	`204 No Content`
Resource not found	`404 Not Found` + error message
Invalid body	`400 Bad Request` + error message

Key Takeaways

REST is a set of conventions for how clients and servers communicate over HTTP — not a library
Resources are nouns in URLs; HTTP methods are the verbs that act on them
The four HTTP methods — GET, POST, PUT, DELETE — map directly to Read, Create, Update, Delete
Status codes tell clients what happened without reading the response body — use them correctly
URL design: plural nouns, no verbs, kebab-case, max 2 nesting levels
Query strings handle filtering, sorting, and pagination — not new endpoints

What's Next?

With a solid REST API foundation, natural next steps include:

Authentication middleware — protecting routes with JWT tokens so only authorised users can call PUT and DELETE
Input validation — using express-validator or zod to validate request bodies cleanly instead of manual checks
Error handling middleware — a centralised error handler so you don't repeat res.status(500) in every route
Router modules — splitting routes into routes/users.js, routes/posts.js so app.js stays clean as the API grows
Database integration — swapping the in-memory array for a real database like PostgreSQL, MongoDB, or SQLite

REST is the foundation every backend developer needs. Master these conventions and every API — whether you're building it or consuming it — will make immediate sense.

Next up: securing your REST API with JWT authentication — adding an auth middleware that turns your open endpoints into protected resources. 🚀

推荐订阅源

DEV Community