Express Router and Routing: Routes, Params, Prefixes

Routing in Express maps an HTTP method and a path to a handler function: app.get('/users', handler) answers GET requests to /users, and app.post(), app.put() and app.delete() do the same for the other methods. A segment that starts with a colon, as in /users/:id, is a route parameter whose value lands in req.params. To keep a growing app in order, put related routes in an express.Router() and mount it under a prefix with app.use('/api', router).

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

const users = [
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Linus' },
];
let nextId = 3;

app.get('/users', (req, res) => {
    res.json(users);
});

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

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

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

app.listen(3000);

GET /users/2 answers {"id":2,"name":"Linus"}. Route parameters are always strings, which is why the handler compares with Number(req.params.id). Send POST /users with the body {"name": "Grace"} to get 201, then DELETE /users/1 and GET /users to see the list change.

express.Router() with a prefix

A router is a mini app with its own routes and middleware. Its paths are relative: a route written as /:id inside a router mounted at /api/books answers /api/books/:id. In a real project each router lives in its own file and ends with module.exports = router.

const express = require('express');

// routes/books.js
const books = express.Router();
const list = [{ id: 1, title: 'Dune' }];

books.get('/', (req, res) => {
    res.json(list);
});

books
    .route('/:id')
    .get((req, res) => {
        res.json(list.find((b) => b.id === Number(req.params.id)) ?? null);
    })
    .put((req, res) => {
        res.json({ updated: req.params.id });
    })
    .delete((req, res) => {
        res.json({ deleted: req.params.id });
    });

// server.js
const app = express();
app.use('/api/books', books);

// GET /api/books/1
app.listen(3000);

GET /api/books/1 returns {"id":1,"title":"Dune"}. router.route('/:id') writes the path once and chains one handler per method; send PUT /api/books/1 and you get {"updated":"1"}. Change the mount path to /v2/books and the same router answers there instead.

Route order: the first match wins

Express tries routes in the order you register them and stops at the first one that sends a response. A parameter route catches anything in its position, so a fixed path registered after it is never reached:

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

app.get('/users/:id', (req, res) => {
    res.json({ route: '/users/:id', id: req.params.id });
});

app.get('/users/new', (req, res) => {
    res.json({ route: '/users/new' });
});

// Runs only when no route above answered.
app.use((req, res) => {
    res.status(404).json({ error: `Cannot ${req.method} ${req.path}` });
});

// GET /users/new
app.listen(3000);

GET /users/new answers {"route":"/users/:id","id":"new"}: the parameter route was registered first and took it. Move the /users/new route above /users/:id and run again to get {"route":"/users/new"}. Then send GET /books to reach the 404 handler at the bottom.

The 404 handler

Express answers an unmatched request with its own HTML page, Cannot GET /books. For an API you usually want JSON, so add an app.use() with no path as the very last route, as in the block above. It runs only when every route before it passed the request on. Errors thrown by handlers are a different case with their own four-argument handler, covered in Express error handling.

Route paths in Express 5

Express 5 changed the path syntax, and most snippets online are written for Express 4:

A bare * or a ? after a parameter throws a TypeError when the route is registered, so the app does not start.

Common mistakes

Registering the 404 handler first. app.use() with no path matches everything, so every request gets the 404. Keep it at the bottom.

Forgetting the prefix is removed. Inside a router mounted at /api, req.path does not include /api. Use req.originalUrl when you need the full path.

Comparing a parameter with a number. req.params.id === 1 is always false because req.params.id is the string '1'.