Express req.params, req.query and req.body Explained

In Express, req.params holds the values of named segments in the route path (/users/:id gives req.params.id), req.query holds the query string after the ? (/search?q=node gives req.query.q), and req.body holds the data sent in the request body. req.params and req.query are filled on every request, but req.body stays undefined until a body parser such as app.use(express.json()) reads it. Values in params and query are always strings.

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

app.get('/users/:userId/posts', (req, res) => {
    res.json({ params: req.params, query: req.query });
});

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

// GET /users/7/posts?sort=new&limit=2
app.listen(3000);

The first request answers {"params":{"userId":"7"},"query":{"sort":"new","limit":"2"}}. Note the quotes: 7 and 2 are strings, so convert them with Number() before you do math or compare with numbers. Now switch the method to POST, keep the path /users/7/posts and send the body {"title": "Hello", "draft": true}: the answer is 201 with "body":{"title":"Hello","draft":true}, where true is a real boolean because it came from JSON.

req.params vs req.query vs req.body

A route can have several parameters, and each name becomes a key of req.params: /teams/:teamId/members/:memberId gives both ids. A hyphen or a dot also separates them, so /flights/:from-:to turns /flights/LAX-SFO into { from: 'LAX', to: 'SFO' }.

req.query with repeated and missing keys

A key that appears twice becomes an array, and a key that is missing is undefined, so give options a default:

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

app.get('/products', (req, res) => {
    const page = Number(req.query.page ?? 1);
    const tags = [].concat(req.query.tag ?? []);
    res.json({ page, tags, raw: req.query });
});

// GET /products?tag=red&tag=sale
app.listen(3000);

The answer is {"page":1,"tags":["red","sale"],"raw":{"tag":["red","sale"]}}. Send GET /products?tag=red&page=3 and tags is still an array, ["red"], because [].concat() turns one string or an array into an array. Express 5 parses query strings with Node's simple parser, so ?filter[size]=m gives the key "filter[size]", not a nested object; Express 4 nested it.

req.body needs express.json()

Node delivers the body as a stream of bytes. express.json() reads it, parses it, and sets req.body, but only when the request has Content-Type: application/json. HTML forms send application/x-www-form-urlencoded, which needs express.urlencoded() instead.

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

app.post('/signup', (req, res) => {
    const { email, name } = req.body ?? {};
    if (!email) {
        return res.status(400).json({ error: 'email is required' });
    }
    res.status(201).json({ email, name: name ?? 'anonymous' });
});

app.get('/', (req, res) => {
    res.send('Send POST /signup with a JSON body');
});

app.listen(3000);

Send POST /signup with the body {"email": "ada@example.com"} and you get 201 with {"email":"ada@example.com","name":"anonymous"}. Send an empty body and you get 400. The ?? {} matters: without it, destructuring undefined throws a TypeError on any request that has no JSON body. For real validation of the shape and types, use a schema library such as zod.

req.headers and req.get()

req.headers is an object of every request header, with lowercase names. req.get(name) reads one header and ignores case, so req.get('Content-Type') and req.get('content-type') return the same value. A few other properties you will use:

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

app.get('/whoami', (req, res) => {
    res.json({
        method: req.method,
        path: req.path,
        originalUrl: req.originalUrl,
        agent: req.get('User-Agent') ?? null,
        token: req.get('authorization') ?? null,
    });
});

// GET /whoami?debug=1
app.listen(3000);

path is /whoami and originalUrl is /whoami?debug=1. Add the header Authorization: Bearer abc in the request bar and send it again: token becomes "Bearer abc". Inside a router mounted with app.use('/api', router), req.path loses the /api prefix while req.originalUrl keeps it (Express routing explains mounting).

Common mistakes

Reading req.body on a GET request. Browsers and most clients send no body with GET. Put GET options in the query string.

Testing a query flag for truthiness. ?admin=false gives the string 'false', which is truthy, so if (req.query.admin) passes. Compare strings: req.query.admin === 'true'.

Sending JSON without the header. A client that posts JSON as text/plain gets req.body === undefined. Set Content-Type: application/json on the client.