📬 Request and Response Objects

The Two Objects

When a request matches a route, Express calls your handler with (req, res). The request object (req) carries everything the client sent — the URL, headers, query string, and body. The response object (res) is how you reply — you set a status, maybe some headers, and send a body.

Reading the Request

Here are the request properties you'll reach for constantly, each shown with the URL or input that populates it:

A single handler often reads several of these at once:

app.get('/users/:id/posts', (req, res) => {
  const userId = req.params.id;                 // from the path
  const page   = Number(req.query.page) || 1;   // from the ?query
  const agent  = req.get('User-Agent');         // a header, via req.get()

  console.log(`User ${userId}, page ${page}, from ${agent}`);
  res.json({ userId, page });
});

Working with the Body

The body is where POST, PUT, and PATCH requests carry their payload. Unlike params and query, the body is not parsed automatically — you must register a body-parsing middleware first, or req.body will be undefined.

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

// Built-in parsers — register these BEFORE your routes:
app.use(express.json());                          // application/json
app.use(express.urlencoded({ extended: true }));  // HTML form posts

app.post('/users', (req, res) => {
  const { name, email, password } = req.body;

  // Never trust the client — validate before using:
  if (!name || !email || !password) {
    return res.status(400).json({ error: 'name, email and password are required' });
  }

  // (Imagine we save the user here...)
  res.status(201).json({ message: 'User created', user: { name, email } });
});

Send a matching request with curl:

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","password":"secret"}'

{"message":"User created","user":{"name":"Ada","email":"ada@example.com"}}

Sending a Response

The response object offers a method for every kind of reply. You call exactly one terminating method per request — sending two responses throws an error.

send vs. json

// res.send() is flexible — it guesses the Content-Type:
app.get('/text', (req, res) => res.send('Hello World'));          // text/html
app.get('/html', (req, res) => res.send('<h1>Hi</h1>'));          // text/html

// res.json() is explicit — always application/json, always stringified:
app.get('/api/user', (req, res) => {
  res.json({ id: 1, name: 'Ada', roles: ['admin'] });
});

For APIs, prefer res.json(): it makes your intent obvious and guarantees the correct content type even for arrays and edge cases like null.

Redirects and files

const path = require('path');

// Redirect (302 by default; pass a code for others):
app.get('/old', (req, res) => res.redirect('/new'));
app.get('/moved', (req, res) => res.redirect(301, '/new-home'));

// Send a file — use an absolute path:
app.get('/report', (req, res) => {
  res.sendFile(path.join(__dirname, 'files', 'report.pdf'));
});

// Prompt a download in the browser:
app.get('/report/download', (req, res) => {
  res.download(path.join(__dirname, 'files', 'report.pdf'), 'annual-report.pdf');
});

Status Codes

The status code is how a client (or another program) knows what happened without reading your message. Setting the right one is a hallmark of a well-behaved API. res.status() is chainable, so it reads naturally before the body method.

app.get('/api/products', (req, res) => {
  res.json(products);                         // 200 OK is the default
});

app.post('/api/products', (req, res) => {
  const created = create(req.body);
  res.status(201).json(created);              // 201 Created
});

app.get('/api/products/:id', (req, res) => {
  const product = find(req.params.id);
  if (!product) {
    return res.status(404).json({ error: 'Product not found' });   // 404
  }
  res.json(product);
});

app.delete('/api/products/:id', (req, res) => {
  remove(req.params.id);
  res.status(204).end();                      // 204 No Content — no body
});

Headers & Cookies

Setting response headers

app.get('/api/data', (req, res) => {
  // One at a time:
  res.set('X-API-Version', '1.0.0');

  // Or several at once:
  res.set({
    'Cache-Control': 'no-cache',
    'X-Powered-By': 'Bootcamp'
  });

  res.json({ message: 'Hello' });
});

Cookies

Use res.cookie() to set a cookie and res.clearCookie() to remove it. For anything touching a session, always set the security options:

// A hardened session cookie:
app.post('/login', (req, res) => {
  // ...authenticate the user...
  res.cookie('sessionId', 'abc123', {
    httpOnly: true,                 // JS in the browser can't read it (blocks XSS theft)
    secure: true,                   // only sent over HTTPS
    sameSite: 'strict',             // not sent on cross-site requests (blocks CSRF)
    maxAge: 24 * 60 * 60 * 1000     // 1 day, in milliseconds
  });
  res.redirect('/dashboard');
});

app.post('/logout', (req, res) => {
  res.clearCookie('sessionId');
  res.redirect('/login');
});

A Consistent Response Shape

APIs are far easier to consume when every response follows the same structure. A small helper keeps success and error replies uniform across your whole app:

// A single helper for every API response
function apiResponse(res, { data = null, error = null, status = 200 }) {
  return res.status(status).json({
    success: error === null,
    timestamp: new Date().toISOString(),
    data,
    error
  });
}

// Used with modern async handlers:
app.get('/api/users/:id', async (req, res, next) => {
  try {
    const user = await db.findUser(req.params.id);
    if (!user) {
      return apiResponse(res, { error: 'User not found', status: 404 });
    }
    return apiResponse(res, { data: user });
  } catch (err) {
    next(err);   // let the error-handling middleware format 500s
  }
});

// 200 OK
{ "success": true,  "timestamp": "2026-07-31T10:00:00.000Z", "data": { "id": 1 }, "error": null }

// 404 Not Found
{ "success": false, "timestamp": "2026-07-31T10:00:01.000Z", "data": null, "error": "User not found" }

Practice & Quiz

app.get('/inspect/:id', (req, res) => {
  res.json({
    id: req.params.id,
    page: Number(req.query.page) || 1,
    userAgent: req.get('User-Agent')
  });
});

app.use(express.json());

let items = [];

app.post('/api/items', (req, res) => {
  const { name } = req.body;
  if (!name) {
    return res.status(400).json({ success: false, error: 'name is required' });
  }
  const item = { id: items.length + 1, name };
  items.push(item);
  res.status(201).json({ success: true, data: item });
});

Best Practices & Pitfalls

✅ Do

• Validate and type-convert everything from req.params, req.query, and req.body
• Return the most specific status code that fits the outcome
• Use res.json() for API data and keep a single consistent response shape
• Set httpOnly, secure, and sameSite on any session cookie
• return your response calls inside branches so code below doesn't run

❌ Don't

• Send more than one response per request — it throws "headers already sent"
• Read req.body without a body parser registered first
• Return 200 for everything — status codes are part of your API's contract
• Put secrets or personal data in the URL/query string — they get logged

// 🐛 Both branches can run — the second response throws:
app.get('/x', (req, res) => {
  if (!valid) res.status(400).json({ error: 'bad' });   // no return!
  res.json({ ok: true });                                // runs anyway → crash
});

// ✅ return early so only one response is sent:
app.get('/x', (req, res) => {
  if (!valid) return res.status(400).json({ error: 'bad' });
  res.json({ ok: true });
});

Summary

📚 Additional Resources

• Express — Request object API
• Express — Response object API
• MDN — HTTP response status codes
• MDN — Using HTTP cookies

🚀 What's Next?

You can now read any request and shape any response. The next step is turning these building blocks into a clean, predictable API design that other developers can pick up instantly — the conventions of REST principles.