🔎 Query Parameters & Body Parsing

Where Request Data Lives

Every incoming HTTP request is a little parcel with several compartments. Express exposes each one on the req object. Knowing which compartment holds what is the difference between code that "just works" and an afternoon of confused logging.

A useful analogy: imagine walking up to a library desk.

• Route params are like naming the exact book — "I want book #123." Built into the address itself.
• Query params are the follow-up refinements — "sorted by author, only the ones from this year." Optional tweaks to the main request.
• Request body is handing over a filled-in form — a chunk of structured data too big for the address line.
• Headers are the context — who you are, what format you can read.
• Cookies are the librarian remembering you from last time.

This lesson focuses on the two you'll touch most: query params and the body.

Route Params vs Query Params

Both live in the URL, and beginners mix them up constantly. Look at where each sits in the address:

// Route param: declared with a colon in the path
app.get('/users/:id', (req, res) => {
  res.json({ requestedId: req.params.id }); // "123"  (always a string)
});

// Query params: no special route setup needed — Express parses them for you
app.get('/users', (req, res) => {
  res.json({ query: req.query }); // { sort: 'name', order: 'asc' }
});

💡 Rule of thumb: if the value names the thing you're fetching, it's a route param. If it modifies how you fetch a collection, it's a query param.

Reading Query Parameters

Express parses the query string into the req.query object automatically — no middleware required. Given the URL /api/products?category=electronics&sort=price&minPrice=100:

app.get('/api/products', (req, res) => {
  console.log(req.query);
  // { category: 'electronics', sort: 'price', minPrice: '100' }

  const { category, sort, minPrice } = req.query;
  console.log(category); // 'electronics'
  console.log(minPrice); // '100'  ← a STRING, not the number 100!

  res.json({ received: req.query });
});

A few more things to keep in mind about req.query:

• A missing parameter is undefined, never null.
• Key names are case-sensitive: ?Page=2 is not ?page=2.
• A repeated key like ?tag=a&tag=b can arrive as an array — more on that shortly.
• The values are URL-decoded for you, so ?q=hello%20world becomes 'hello world'.

Parsing & Validating Query Params

Because query values are strings, the pattern for numbers is always: parse, then validate. Never trust that the client sent a sensible value.

app.get('/api/products', (req, res) => {
  const { category, minPrice, maxPrice, inStock, page, limit } = req.query;

  // Parse into real types, with sensible defaults
  const filters = {
    category,                                        // keep as string
    minPrice: minPrice !== undefined ? Number(minPrice) : undefined,
    maxPrice: maxPrice !== undefined ? Number(maxPrice) : undefined,
    inStock: inStock === 'true',                     // string → boolean
    page: Number.parseInt(page ?? '1', 10),          // default page 1
    limit: Number.parseInt(limit ?? '20', 10)        // default 20 per page
  };

  // Validate AFTER parsing — Number('abc') is NaN
  if (filters.minPrice !== undefined && Number.isNaN(filters.minPrice)) {
    return res.status(400).json({ error: 'minPrice must be a number' });
  }
  if (!Number.isInteger(filters.page) || filters.page < 1) {
    return res.status(400).json({ error: 'page must be a positive integer' });
  }
  if (!Number.isInteger(filters.limit) || filters.limit < 1 || filters.limit > 100) {
    return res.status(400).json({ error: 'limit must be between 1 and 100' });
  }

  res.json({ appliedFilters: filters });
});

Array & Repeated Params

Query strings can express lists, and clients do it in several styles. Express (via its default qs parser) interprets them like this:

The gotcha: the same key can arrive as a string or an array depending on how many values the client sent. Normalize it to always be an array before you use it:

app.get('/api/products', (req, res) => {
  const raw = req.query.color;

  let colors;
  if (Array.isArray(raw)) {
    colors = raw;                       // already ['red', 'blue']
  } else if (typeof raw === 'string') {
    colors = raw.split(',');            // 'red,blue' → ['red', 'blue']
  } else {
    colors = [];                        // undefined → empty list
  }

  res.json({ colors }); // consistently an array, no matter the input style
});

💡 A tidy one-liner: const colors = [].concat(req.query.color ?? []).flatMap(c => String(c).split(',')); handles the string, array, and missing cases together — but the explicit version above is easier to read and debug while you're learning.

Pagination, Filtering & Sorting

These three patterns power almost every "list" endpoint. Let's build a paginated articles endpoint end to end.

app.get('/api/articles', (req, res) => {
  // 1. Parse pagination params with defaults
  const page = Number.parseInt(req.query.page ?? '1', 10);
  const limit = Number.parseInt(req.query.limit ?? '10', 10);

  // 2. Validate
  if (!Number.isInteger(page) || page < 1) {
    return res.status(400).json({ error: 'page must be a positive integer' });
  }
  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
    return res.status(400).json({ error: 'limit must be between 1 and 100' });
  }

  // 3. Optional sort (whitelist the allowed fields — never trust raw input!)
  const allowedSorts = ['title', 'createdAt', 'views'];
  const sort = allowedSorts.includes(req.query.sort) ? req.query.sort : 'createdAt';
  const order = req.query.order === 'asc' ? 'asc' : 'desc';

  // 4. Mock data source
  let articles = Array.from({ length: 95 }, (_, i) => ({
    id: i + 1,
    title: `Article ${i + 1}`,
    views: Math.floor(Math.random() * 1000),
    createdAt: new Date(2026, 0, i + 1).toISOString()
  }));

  // 5. Sort
  articles.sort((a, b) => {
    const dir = order === 'asc' ? 1 : -1;
    return a[sort] > b[sort] ? dir : a[sort] < b[sort] ? -dir : 0;
  });

  // 6. Slice to the current page
  const total = articles.length;
  const start = (page - 1) * limit;
  const pageItems = articles.slice(start, start + limit);

  // 7. Respond with data + metadata the client needs to build controls
  res.json({
    data: pageItems,
    pagination: {
      total,
      page,
      limit,
      totalPages: Math.ceil(total / limit),
      hasNext: start + limit < total,
      hasPrev: page > 1
    }
  });
});

Returning pagination metadata alongside the data is what lets a front-end render "Page 2 of 10" and enable/disable its Next button. Give the client everything it needs in one response.

Body Parsing

Query params are great for small, optional refinements. For substantial data — creating a user, submitting an order — you use the request body. Unlike the query string, Express does not parse bodies automatically; you register the matching middleware.

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

// Two built-in parsers, registered once near the top:
app.use(express.json());                          // for application/json
app.use(express.urlencoded({ extended: true }));  // for HTML form posts

app.post('/api/users', (req, res) => {
  const { username, email, age } = req.body;

  if (!username || !email) {
    return res.status(400).json({ error: 'username and email are required' });
  }

  res.status(201).json({ message: 'User created', user: { username, email, age } });
});

Each parser only activates when the request's Content-Type matches, so it's safe to register both. A JSON request flows through express.json(); a form submission flows through express.urlencoded(); each leaves the result on req.body.

app.use(express.json({ limit: '1mb' }));

app.use(express.urlencoded({
  extended: true,        // allow nested objects/arrays (uses the qs library)
  limit: '1mb',          // cap the body size
  parameterLimit: 1000   // max number of form fields
}));

URL-encoded Form Data

When a classic HTML <form> submits without JavaScript, the browser encodes the fields as application/x-www-form-urlencoded — the same key=value&key=value format as a query string, but in the body. express.urlencoded() parses it onto req.body.

app.use(express.urlencoded({ extended: true }));

app.post('/login', (req, res) => {
  const { username, password, rememberMe } = req.body;

  // Checkboxes are quirky: present as 'on' when checked, absent otherwise
  const shouldRemember = rememberMe === 'on';

  if (username === 'ada' && password === 'secret123') {
    return res.redirect('/dashboard');
  }
  res.redirect('/login?error=invalid_credentials');
});

What extended actually controls

The extended option decides which library parses the body, and that changes how nested field names are interpreted:

<!-- A form with nested field names -->
<form action="/api/profile" method="POST">
  <input name="user[name]"  value="John Doe">
  <input name="user[email]" value="john@example.com">
  <input name="hobbies[]"   value="reading">
  <input name="hobbies[]"   value="hiking">
</form>

💡 Which do I pick? Use extended: true when your forms send nested structures (most modern apps). Use extended: false for strictly flat forms and slightly less overhead. When unsure, true is the friendlier default.

Practice & Quiz

function getPagination(query) {
  // TODO: parse, default, clamp, and compute offset
}
getPagination({ page: '3', limit: '25' }); // { page: 3, limit: 25, offset: 50 }
getPagination({});                          // { page: 1, limit: 20, offset: 0 }
getPagination({ page: '-2', limit: '999' });// { page: 1, limit: 100, offset: 0 }

function getPagination(query) {
  let page = Number.parseInt(query.page ?? '1', 10);
  let limit = Number.parseInt(query.limit ?? '20', 10);

  if (!Number.isInteger(page)) page = 1;
  if (!Number.isInteger(limit)) limit = 20;

  page = Math.max(page, 1);
  limit = Math.min(Math.max(limit, 1), 100);

  return { page, limit, offset: (page - 1) * limit };
}

app.get('/api/users', (req, res) => {
  const { search, role, status } = req.query;
  let users = [
    { id: 1, name: 'Alice Johnson', role: 'admin',  status: 'active' },
    { id: 2, name: 'Bob Smith',     role: 'user',   status: 'inactive' },
    { id: 3, name: 'Carol Williams',role: 'editor', status: 'active' }
  ];

  if (role)   users = users.filter(u => u.role === role);
  if (status) users = users.filter(u => u.status === status);
  if (search) {
    const q = search.toLowerCase();
    users = users.filter(u => u.name.toLowerCase().includes(q));
  }

  res.json({ count: users.length, data: users });
});

Best Practices & Pitfalls

✅ Do

• Treat every req.query value as a string — parse numbers and booleans yourself
• Validate after parsing, checking for NaN and out-of-range values
• Provide defaults for optional params (page, limit, sort order)
• Whitelist sort fields and enum-like values instead of trusting raw input
• Return pagination metadata so clients can build their own controls

❌ Don't

• Do math on a query param without converting it ('100' + 1 === '1001')
• Assume a repeated param is always a string — it may be an array
• Let limit reach your database unbounded (cap it!)
• Forget express.urlencoded() and wonder why form req.body is empty
• Use parseInt(x) without the radix 10

// ❌ req.query.page is a string
const next = req.query.page + 1;          // '2' + 1 → '21'

// ✅ parse first
const page = Number.parseInt(req.query.page ?? '1', 10);
const next = page + 1;                     // 3

Summary

📚 Additional Resources

• Express — req.query
• Express — req.params
• Express — express.urlencoded()
• MDN — URLSearchParams

🚀 What's Next?

You've handled text-based input from the URL and the body. But what about binary data — images, PDFs, videos? Those come in as multipart/form-data, which the built-in parsers don't touch. Next: File uploads with Multer, the middleware built for exactly this job.