🚀 Building RESTful APIs with Express

What REST Actually Means

REST (Representational State Transfer) is an architectural style for networked applications. It isn't a library or a protocol you install — it's a set of conventions layered on top of plain HTTP. When an API follows those conventions, any developer who knows HTTP can guess how it works without reading much documentation. That predictability is the whole point.

Express is a thin, unopinionated web framework for Node.js. It doesn't force REST on you, but it makes REST easy: a route is a method plus a path plus a handler, and that maps almost one-to-one onto REST's "verb acts on a resource" model.

🍽️ The restaurant analogy. A RESTful API is like a restaurant. The resources (users, products) are menu items. The HTTP methods are how you place your order — "bring me" (GET), "add this" (POST), "change my order" (PUT/PATCH), "cancel it" (DELETE). The routes are sections of the menu, and the responses are what the waiter brings back. Because every restaurant follows the same ordering ritual, you can walk into a new one and know what to do.

REST Architectural Principles

REST is defined by a handful of constraints. You don't have to memorize the theory, but understanding each one explains why good APIs are shaped the way they are:

HTTP Methods & CRUD

The heart of REST is the mapping between HTTP methods and the four data operations — Create, Read, Update, Delete. Learn this table and most of REST falls into place:

The difference between PUT and PATCH trips up beginners: PUT replaces the whole resource (any field you omit gets cleared), while PATCH applies only the fields you send. Use PATCH for "update one thing", PUT for "here is the complete new version".

A Complete CRUD API

Here is a full CRUD API for a users resource. It uses an in-memory array so you can run it immediately with just npm install express — in a real app the array would be a database. The code targets modern Express and uses const/let and arrow functions throughout.

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

// Parse JSON request bodies (built into Express — no body-parser needed)
app.use(express.json());

// In-memory "database"
let users = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' },
];
let nextId = 3;

// READ — all users
app.get('/api/users', (req, res) => {
  res.status(200).json(users);
});

// READ — one user
app.get('/api/users/:id', (req, res) => {
  const user = users.find((u) => u.id === Number(req.params.id));
  if (!user) {
    return res.status(404).json({ message: 'User not found' });
  }
  res.status(200).json(user);
});

// CREATE
app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ message: 'Name and email are required' });
  }
  const newUser = { id: nextId++, name, email };
  users.push(newUser);
  // 201 Created + a Location header pointing at the new resource
  res.status(201).location(`/api/users/${newUser.id}`).json(newUser);
});

// UPDATE (full replace)
app.put('/api/users/:id', (req, res) => {
  const id = Number(req.params.id);
  const index = users.findIndex((u) => u.id === id);
  if (index === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ message: 'PUT requires the full resource' });
  }
  users[index] = { id, name, email };
  res.status(200).json(users[index]);
});

// UPDATE (partial)
app.patch('/api/users/:id', (req, res) => {
  const id = Number(req.params.id);
  const index = users.findIndex((u) => u.id === id);
  if (index === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  users[index] = { ...users[index], ...req.body, id }; // keep id immutable
  res.status(200).json(users[index]);
});

// DELETE
app.delete('/api/users/:id', (req, res) => {
  const id = Number(req.params.id);
  const index = users.findIndex((u) => u.id === id);
  if (index === -1) {
    return res.status(404).json({ message: 'User not found' });
  }
  users.splice(index, 1);
  res.status(204).send(); // 204 = success, no body
});

app.listen(3000, () => {
  console.log('API server running at http://localhost:3000');
});

Notice the repeating shape: every handler validates input, checks existence, mutates data, and returns a resource plus a status code. The flowchart below shows how a single router fans out into those handlers:

Resource Naming & Nesting

Good URL design makes an API feel intuitive. A few rules cover almost every case:

• Use nouns, not verbs. /users, not /getUsers. The HTTP method already is the verb.
• Use plural collections. /users and /users/42, not /user/42.
• Nest to show relationships. /users/42/posts reads as "posts belonging to user 42".
• Keep it shallow and predictable. Prefer /users/42 over /user-management/find/42.
• Use query params for filtering/sorting, not new paths: /products?category=electronics&sort=price.
• Hyphenate multi-word resources. /blog-posts reads better than /blogposts.

Nested resources are just routes with two parameters. Here's a user's posts:

const express = require('express');
// mergeParams lets this router see :userId from the parent route
const router = express.Router({ mergeParams: true });

// GET /api/users/:userId/posts
router.get('/', (req, res) => {
  const userId = Number(req.params.userId);
  const userPosts = posts.filter((p) => p.userId === userId);
  res.status(200).json(userPosts);
});

// POST /api/users/:userId/posts
router.post('/', (req, res) => {
  const userId = Number(req.params.userId);
  if (!users.some((u) => u.id === userId)) {
    return res.status(404).json({ message: 'User not found' });
  }
  const { title, content } = req.body;
  if (!title || !content) {
    return res.status(400).json({ message: 'Title and content are required' });
  }
  const newPost = {
    id: posts.length + 1,
    userId,
    title,
    content,
    createdAt: new Date().toISOString(),
  };
  posts.push(newPost);
  res.status(201).json(newPost);
});

module.exports = router;
// Mounted in app.js:  app.use('/api/users/:userId/posts', postsRouter);

Responses & Status Codes

Two things make an API pleasant to consume: the right status code and a consistent response shape. Clients write code against both, so changing them later breaks integrations.

The status codes you'll actually use

A consistent response envelope

Wrap every response in the same structure so clients never have to guess. Small helper functions keep it DRY:

// util/apiResponse.js
const sendSuccess = (res, statusCode, data, meta = {}) =>
  res.status(statusCode).json({ success: true, data, meta });

const sendError = (res, statusCode, message, details = null) => {
  const body = { success: false, error: { message } };
  if (details) body.error.details = details;
  return res.status(statusCode).json(body);
};

module.exports = { sendSuccess, sendError };

const { sendSuccess, sendError } = require('./util/apiResponse');

app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  const errors = [];
  if (!name) errors.push({ field: 'name', message: 'Name is required' });
  if (!email) errors.push({ field: 'email', message: 'Email is required' });
  if (errors.length) {
    return sendError(res, 400, 'Validation failed', errors);
  }
  const newUser = { id: nextId++, name, email, createdAt: new Date().toISOString() };
  users.push(newUser);
  return sendSuccess(res, 201, newUser);
});

{
  "success": true,
  "data": { "id": 3, "name": "Carol", "email": "carol@example.com" },
  "meta": {}
}

Pagination, Filtering & Sorting

Returning ten thousand rows in one response is slow and wasteful. Real collections support pagination (limit how many come back), filtering (narrow the set), and sorting — all through query parameters. Here's a single endpoint that does all three:

// GET /api/products?category=electronics&minPrice=10&sort=price&order=desc&page=2&limit=20
app.get('/api/products', (req, res) => {
  let result = [...products];

  // --- Filtering ---
  const { category, minPrice, maxPrice, search } = req.query;
  if (category) result = result.filter((p) => p.category === category);
  if (minPrice) result = result.filter((p) => p.price >= Number(minPrice));
  if (maxPrice) result = result.filter((p) => p.price <= Number(maxPrice));
  if (search) {
    const term = search.toLowerCase();
    result = result.filter((p) => p.name.toLowerCase().includes(term));
  }

  // --- Sorting ---
  if (req.query.sort) {
    const field = req.query.sort;
    const dir = req.query.order === 'desc' ? -1 : 1;
    result.sort((a, b) => (a[field] > b[field] ? dir : a[field] < b[field] ? -dir : 0));
  }

  // --- Pagination ---
  const page = Math.max(1, Number(req.query.page) || 1);
  const limit = Math.min(100, Number(req.query.limit) || 10); // cap the limit!
  const total = result.length;
  const start = (page - 1) * limit;
  const pageItems = result.slice(start, start + limit);

  res.status(200).json({
    success: true,
    data: pageItems,
    meta: {
      total,
      page,
      limit,
      pages: Math.ceil(total / limit),
    },
  });
});

The parameter names above aren't invented — they're conventions shared across production APIs:

Versioning & Documentation

Once real clients depend on your API, you can't change its shape without warning — you'd break their apps. Versioning lets you ship a new design while the old one keeps working.

Versioning approaches

• URL path (most common): /api/v1/users — obvious and easy to route
• Query parameter: /api/users?version=1
• Header / content negotiation: Accept: application/vnd.company.v1+json

URL versioning is trivial in Express — each version is just a router mounted at a different prefix:

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

const v1Users = require('./routes/v1/users');
const v2Users = require('./routes/v2/users');

app.use('/api/v1/users', v1Users);
app.use('/api/v2/users', v2Users);

// routes/v2/users.js — v2 returns a richer payload than v1
const router = express.Router();
router.get('/', (req, res) => {
  const data = users.map((u) => ({
    id: u.id,
    name: u.name,
    email: u.email,
    role: u.role,
    createdAt: u.createdAt,
  }));
  res.status(200).json({ data, meta: { total: data.length, version: 'v2' } });
});
module.exports = router;

Documenting with OpenAPI / Swagger

An undocumented API is hard to adopt. OpenAPI (formerly Swagger) is the standard description format; swagger-ui-express turns it into an interactive, testable web page.

// npm install swagger-jsdoc swagger-ui-express
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const spec = swaggerJsdoc({
  definition: {
    openapi: '3.0.0',
    info: { title: 'User API', version: '1.0.0' },
    servers: [{ url: 'http://localhost:3000' }],
  },
  apis: ['./routes/*.js'], // read JSDoc @swagger comments from these files
});

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec));

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: Returns a paginated list of users
 *     parameters:
 *       - in: query
 *         name: page
 *         schema: { type: integer, default: 1 }
 *     responses:
 *       200:
 *         description: A list of users
 */
app.get('/api/users', (req, res) => { /* ... */ });

Hands-on Exercise

const express = require('express');
const router = express.Router();

let products = [
  { id: 1, name: 'Wireless Mouse', price: 25, category: 'electronics' },
  { id: 2, name: 'Desk Lamp', price: 40, category: 'home' },
];
let nextId = 3;

router.get('/', (req, res) => {
  let result = [...products];
  if (req.query.category) {
    result = result.filter((p) => p.category === req.query.category);
  }
  if (req.query.sort) {
    const field = req.query.sort;
    const dir = req.query.order === 'desc' ? -1 : 1;
    result.sort((a, b) => (a[field] > b[field] ? dir : a[field] < b[field] ? -dir : 0));
  }
  const page = Math.max(1, Number(req.query.page) || 1);
  const limit = Math.min(100, Number(req.query.limit) || 10);
  const total = result.length;
  const data = result.slice((page - 1) * limit, page * limit);
  res.json({ success: true, data, meta: { total, page, limit, pages: Math.ceil(total / limit) } });
});

router.post('/', (req, res) => {
  const { name, price, category } = req.body;
  if (!name || price == null) {
    return res.status(400).json({ success: false, error: { message: 'name and price are required' } });
  }
  const product = { id: nextId++, name, price, category: category || 'uncategorized' };
  products.push(product);
  res.status(201).json({ success: true, data: product });
});

router.get('/:id', (req, res) => {
  const product = products.find((p) => p.id === Number(req.params.id));
  if (!product) return res.status(404).json({ success: false, error: { message: 'Not found' } });
  res.json({ success: true, data: product });
});

router.delete('/:id', (req, res) => {
  const i = products.findIndex((p) => p.id === Number(req.params.id));
  if (i === -1) return res.status(404).json({ success: false, error: { message: 'Not found' } });
  products.splice(i, 1);
  res.status(204).send();
});

module.exports = router;

// app.js
const express = require('express');
const app = express();
app.use(express.json());
app.use('/api/products', require('./routes/products'));
app.listen(3000, () => console.log('http://localhost:3000'));

Best Practices

Summary & Quiz

📚 Further Reading

• Express — Routing Guide
• RESTful API Design Guidelines
• OpenAPI Specification
• Microsoft REST API Guidelines
• Stripe API Docs — a gold-standard example

🚀 What's Next?

Your routes are getting repetitive — validating input, logging, checking auth. That cross-cutting logic belongs in middleware. Next, Custom Middleware Development shows you how to build reusable middleware pipelines that keep your handlers clean.