🗺️ Routing and Middleware

Routing Basics

Routing is how an app's endpoints (URIs) respond to client requests. Each route is defined by a method call in the shape app.METHOD(PATH, HANDLER), where METHOD is a lowercase HTTP verb, PATH is a URL pattern, and HANDLER is the function that runs on a match.

📮 The mail-sorting analogy. Routing is a post office. The HTTP method is the service class (standard, express, registered); the path is the destination department; a route parameter is a specific mailbox within it; and the handler is the clerk who processes that kind of mail for that department.

const express = require('express');
const app = express();
app.use(express.json());

app.get('/', (req, res) => res.send('Hello World!'));

app.post('/users', (req, res) => {
  res.status(201).json({ created: req.body });
});

app.put('/users/:id', (req, res) => {
  res.send(`Updated user ${req.params.id}`);
});

app.delete('/users/:id', (req, res) => {
  res.status(204).end();
});

app.listen(3000, () => console.log('Listening on 3000'));

Notice the status codes: 201 Created after a successful POST, and 204 No Content after a DELETE with nothing to return. Choosing accurate status codes is part of good routing, not an afterthought.

Route & Query Parameters

Express gives you two ways to receive data through the URL, and it's important to know which is which.

Route parameters — req.params

// One parameter
app.get('/users/:userId', (req, res) => {
  res.send(`User ID: ${req.params.userId}`);
});

// Nested resources with multiple parameters
app.get('/users/:userId/posts/:postId', (req, res) => {
  const { userId, postId } = req.params;
  res.json({ userId, postId });
});

A request to /users/123/posts/456 sets userId to "123" and postId to "456". The nested path mirrors the real relationship: posts belong to a user.

Query parameters — req.query

app.get('/api/products', (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 20;
  const category = req.query.category;
  const minPrice = req.query.minPrice ? parseFloat(req.query.minPrice) : undefined;

  const filter = {};
  if (category) filter.category = category;
  if (minPrice !== undefined) filter.price = { $gte: minPrice };

  res.json({
    filter,
    pagination: { currentPage: page, itemsPerPage: limit }
  });
});

Combined, a URL like /api/products?category=electronics&minPrice=100&page=2&limit=10 gives you filtering and pagination in one clean, bookmarkable endpoint.

Chained Route Handlers

A route can take more than one handler function. Each behaves like route-specific middleware: it runs in order, and any one of them can end the cycle or call next() to advance. This lets you break a request into small, single-purpose steps.

// Step 1: validate the id format
function validateUserId(req, res, next) {
  if (!/^[0-9a-fA-F]{24}$/.test(req.params.id)) {
    return res.status(400).json({ error: 'Invalid user ID format' });
  }
  next();
}

// Step 2: load the user, attach to req
async function loadUser(req, res, next) {
  try {
    const user = await findUserById(req.params.id);
    if (!user) return res.status(404).json({ error: 'User not found' });
    req.user = user;      // hand off to the next function
    next();
  } catch (err) {
    next(err);            // forward to the error handler
  }
}

// Step 3: respond
function sendUser(req, res) {
  res.json(req.user);
}

app.get('/users/:id', validateUserId, loadUser, sendUser);

Each function does exactly one thing, which makes them reusable — validateUserId and loadUser can be shared across GET, PUT, and DELETE routes for the same resource.

Modular Routers

Piling every route into one file stops scaling quickly. express.Router() creates a mini-application — its own middleware and routes — that you can define in a separate file and mount at a path prefix.

File: routes/userRoutes.js

const express = require('express');
const router = express.Router();
const userController = require('../controllers/userController');

router.get('/', userController.getAllUsers);
router.post('/', userController.createUser);
router.get('/:id', userController.getUserById);
router.put('/:id', userController.updateUser);
router.delete('/:id', userController.deleteUser);

module.exports = router;

File: app.js

const express = require('express');
const userRoutes = require('./routes/userRoutes');
const productRoutes = require('./routes/productRoutes');

const app = express();
app.use(express.json());

// Mount routers at their prefixes
app.use('/api/users', userRoutes);
app.use('/api/products', productRoutes);

app.listen(3000, () => console.log('Listening on 3000'));

Because the router is mounted at /api/users, its internal router.get('/') answers GET /api/users, and router.get('/:id') answers GET /api/users/:id. Each resource gets its own file, and the main app stays a short table of contents.

Writing Custom Middleware

A middleware is just a function with the signature (req, res, next). The most flexible pattern is a middleware factory: a function that takes options and returns a configured middleware. This lets you reuse one middleware with different settings on different routes.

// A configurable rate limiter (in-memory demo)
function rateLimit({ windowMs = 60_000, max = 100, message = 'Too many requests' } = {}) {
  const hits = new Map();

  return (req, res, next) => {
    const ip = req.ip;
    const now = Date.now();
    const entry = hits.get(ip);

    if (!entry || now - entry.start > windowMs) {
      hits.set(ip, { count: 1, start: now });
      return next();
    }

    entry.count++;
    if (entry.count > max) {
      return res.status(429).json({ error: message });
    }
    next();
  };
}

// Generous limit globally...
app.use(rateLimit({ windowMs: 15 * 60_000, max: 100 }));

// ...but strict on login
app.use('/api/login', rateLimit({ windowMs: 60 * 60_000, max: 5 }));

The same factory idea powers authentication guards, feature flags, and role checks — anywhere you want "the same behavior, tuned per route."

Error-Handling Middleware

Error-handling middleware is special: Express recognizes it by its four arguments — (err, req, res, next). When any middleware calls next(err) with an argument, Express skips all remaining regular middleware and jumps straight to the first error handler.

The professional pattern pairs custom error classes with a single central handler. The classes carry a status code and mark expected ("operational") errors so you can safely show their message to clients:

// errors.js
class AppError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode = statusCode;
    this.status = `${statusCode}`.startsWith('4') ? 'fail' : 'error';
    this.isOperational = true;
    Error.captureStackTrace(this, this.constructor);
  }
}

class NotFoundError extends AppError {
  constructor(msg = 'Resource not found') { super(msg, 404); }
}
class ValidationError extends AppError {
  constructor(msg = 'Validation failed') { super(msg, 400); }
}

module.exports = { AppError, NotFoundError, ValidationError };

// A route that throws, then forwards to the handler
app.get('/api/users/:id', async (req, res, next) => {
  try {
    const user = await findUserById(req.params.id);
    if (!user) throw new NotFoundError(`User ${req.params.id} not found`);
    res.json(user);
  } catch (err) {
    next(err); // hand off to the error-handling middleware
  }
});

// The ONE central error handler — registered LAST
app.use((err, req, res, next) => {
  err.statusCode = err.statusCode || 500;
  err.status = err.status || 'error';

  if (process.env.NODE_ENV === 'development') {
    return res.status(err.statusCode).json({
      status: err.status, message: err.message, stack: err.stack
    });
  }

  // Production: only leak messages for trusted, operational errors
  if (err.isOperational) {
    return res.status(err.statusCode).json({ status: err.status, message: err.message });
  }
  console.error('UNEXPECTED ERROR', err);
  res.status(500).json({ status: 'error', message: 'Something went wrong' });
});

Hands-on Exercise

// routes/userRoutes.js
const express = require('express');
const router = express.Router();
const { NotFoundError } = require('../errors');

const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];

function validateId(req, res, next) {
  if (!/^\d+$/.test(req.params.id)) {
    return res.status(400).json({ error: 'Invalid id' });
  }
  next();
}

router.get('/', (req, res) => res.json(users));

router.post('/', (req, res) => {
  const user = { id: users.length + 1, name: req.body.name };
  users.push(user);
  res.status(201).json(user);
});

router.get('/:id', validateId, (req, res, next) => {
  const user = users.find(u => u.id === Number(req.params.id));
  if (!user) return next(new NotFoundError(`User ${req.params.id} not found`));
  res.json(user);
});

module.exports = router;

// app.js
const express = require('express');
const userRoutes = require('./routes/userRoutes');
const app = express();

app.use(express.json());
app.use('/api/users', userRoutes);

app.use((err, req, res, next) => {
  const code = err.statusCode || 500;
  res.status(code).json({ error: err.message });
});

app.listen(3000, () => console.log('Listening on 3000'));

Best Practices

Summary & Quiz

📚 Further Reading

• Express — Routing guide
• Express — Error handling
• express-rate-limit (npm)

🚀 What's Next?

You can route requests and handle errors cleanly. Next we'll turn responses into rich HTML pages using template engines — EJS, Pug, and Handlebars — so your server can render dynamic views, not just JSON.