Rutas en Express y express.Router: parámetros y prefijos

El routing en Express asocia un método HTTP y una ruta a una función handler: app.get('/users', handler) responde a las peticiones GET a /users, y app.post(), app.put() y app.delete() hacen lo mismo para los otros métodos. Un segmento que empieza por dos puntos, como en /users/:id, es un parámetro de ruta cuyo valor acaba en req.params. Para mantener ordenada una app que crece, pon las rutas relacionadas en un express.Router() y móntalo bajo un prefijo con 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 responde {"id":2,"name":"Linus"}. Los parámetros de ruta siempre son strings, por eso el handler compara con Number(req.params.id). Envía POST /users con el body {"name": "Grace"} para obtener 201, y luego DELETE /users/1 y GET /users para ver cómo cambia la lista.

express.Router() con un prefijo

Un router es una mini app con sus propias rutas y middleware. Sus rutas son relativas: una ruta escrita como /:id dentro de un router montado en /api/books responde a /api/books/:id. En un proyecto real cada router vive en su propio archivo y termina con 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 devuelve {"id":1,"title":"Dune"}. router.route('/:id') escribe la ruta una sola vez y encadena un handler por método; envía PUT /api/books/1 y obtienes {"updated":"1"}. Cambia la ruta de montaje a /v2/books y el mismo router responde ahí.

El orden de las rutas: gana la primera que coincide

Express prueba las rutas en el orden en que las registras y se detiene en la primera que envía una respuesta. Una ruta con parámetro captura cualquier cosa en esa posición, así que una ruta fija registrada después nunca se alcanza:

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 responde {"route":"/users/:id","id":"new"}: la ruta con parámetro se registró primero y se la quedó. Sube la ruta /users/new por encima de /users/:id y vuelve a ejecutar para obtener {"route":"/users/new"}. Luego envía GET /books para llegar al handler 404 del final.

El handler 404

Express responde a una petición que no coincide con ninguna ruta con su propia página HTML, Cannot GET /books. En una API normalmente quieres JSON, así que añade un app.use() sin ruta como última ruta de todas, como en el bloque de arriba. Solo se ejecuta cuando todas las rutas anteriores han dejado pasar la petición. Los errores que lanzan los handlers son otro caso, con su propio handler de cuatro argumentos, explicado en manejo de errores en Express.

Rutas en Express 5

Express 5 cambió la sintaxis de las rutas, y la mayoría de los ejemplos que hay por internet están escritos para Express 4:

Un * suelto o un ? después de un parámetro lanza un TypeError al registrar la ruta, así que la app no arranca.

Errores comunes

Registrar el handler 404 primero. app.use() sin ruta coincide con todo, así que todas las peticiones reciben el 404. Déjalo al final.

Olvidar que el prefijo se elimina. Dentro de un router montado en /api, req.path no incluye /api. Usa req.originalUrl cuando necesites la ruta completa.

Comparar un parámetro con un número. req.params.id === 1 siempre es false porque req.params.id es el string '1'.