Route Parameters
Route parameters are named placeholders in an Express route path, written with a colon, such as /users/:id. They capture part of the URL and make it available in req.params. You use them whenever a URL identifies a specific item, like a single product, an order or a blog post, so one route can handle every id instead of one route per item.
Reading values from req.params
When a request for /api/products/42 matches the route /api/products/:id, Express sets req.params.id to "42". A path can have several parameters, separated by slashes or other fixed text.
const express = require('express');
const app = express();
// One parameter
app.get('/api/products/:id', (req, res) => {
const id = Number(req.params.id);
if (!Number.isInteger(id)) {
return res.status(400).json({ error: 'id must be a number' });
}
res.json({ productId: id });
});
// Several parameters
app.get('/api/shops/:city/:category/:slug', (req, res) => {
const { city, category, slug } = req.params;
res.json({ city, category, slug });
});
// Parameter plus a query string: /api/users/7/orders?status=paid&page=2
app.get('/api/users/:userId/orders', (req, res) => {
res.json({
user: req.params.userId,
status: req.query.status || 'all',
page: Number(req.query.page) || 1,
});
});
app.listen(3000);
For /api/shops/jaipur/bakery/sweet-crumbs, the second route returns all three values. Express also decodes URL-encoded characters, so %20 becomes a space in req.params.
Parameter names can contain letters, numbers and underscores. Hyphens and dots in the path act as separators, so a route like /flights/:from-:to matches /flights/DEL-BOM and gives you from and to separately. This is handy for readable URLs, but keep patterns simple so that other developers can predict what a path will match.
Notice that the first route checks the value before using it. Anything a user can type into the address bar can reach your handler, including words, negative numbers or very long strings, so treat parameters as untrusted input just like form data.
Route parameters versus query strings
| Route parameter | Query string | |
|---|---|---|
| Looks like | /users/7 | /users?sort=name |
| Read with | req.params | req.query |
| Required? | Yes, or the route does not match | No, every key is optional |
| Use for | Identifying a resource | Filtering, sorting, searching, paging |
A good rule is that the path names the thing and the query string describes how you want to see it. /api/users/7/orders?status=paid reads naturally as "the paid orders of user 7".
Optional parameters and patterns
In Express 4, a question mark makes a parameter optional: /api/archive/:month? matches both /api/archive and /api/archive/march, and req.params.month is undefined in the first case. Express 5 changed this syntax to braces, /api/archive{/:month}, so check which version your project uses. When the same parameter appears in many routes, router.param('id', handler) lets you load or validate it once for all of them.
The ordering bug
Express checks routes in the order you define them and uses the first match. If /api/products/:id comes before /api/products/featured, a request for featured is caught by the parameter route with id set to "featured". Your featured route never runs. Place fixed paths before parameter paths that could swallow them.
The other classic mistake is forgetting that every parameter is a string. Comparing req.params.id === 42 is always false. Convert with Number() and validate, as the first route does, so a request like /api/products/abc returns a clear 400 instead of an odd result.
What to remember
- Define placeholders with
:nameand read them fromreq.params. - Use parameters to identify resources and query strings for options.
- Convert and validate parameter values, since they arrive as strings.
- Put specific routes before general parameter routes.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.