Module F-6·22 min read

The built-in http module, why Express exists, routing, middleware pipelines, route parameters, query strings, and sending JSON responses.

Module F-6 — Building HTTP Servers and REST APIs with Express

Q: When accessing a route parameter in Express (e.g., `/users/:id`), what data type is the parameter `req.params.id`?

It is always a string, regardless of the value provided in the URL. — Express route parameters, as well as query string parameters, are always captured and exposed as strings. Even if a client requests `/users/42`, `req.params.id` will be the string `"42"`. You must manually parse it using `parseInt()` or a similar function before using it mathematically or in strict comparisons.

Q: In an Express middleware function, what happens if you neither send a response (e.g., `res.json()`) nor call `next()`?

The request will hang indefinitely, eventually causing a timeout, because the chain is stalled. — Express relies on the developer to control the flow of execution. A middleware must either terminate the request by sending a response (e.g., `res.send()`, `res.json()`) or hand control to the next middleware by invoking `next()`. If neither is done, the request hangs, leaving the client waiting until the browser or server times out.

Q: What is the correct function signature for a global error-handling middleware in Express?

`app.use((err, req, res, next) => { ... })` — Express identifies an error-handling middleware specifically by its arity (the number of parameters it accepts). It must take exactly four arguments: `(err, req, res, next)`. If you omit `next`, Express will treat it as a standard middleware `(req, res, next)` and it will not correctly catch errors.

What this module covers: Express is the most widely used Node.js web framework — and for good reason. It takes the built-in http module and adds routing, middleware, and a clean request/response API without imposing a rigid structure. This module covers everything you need to build a real REST API: routing, route parameters, query strings, request bodies, middleware pipelines, and error responses. By the end you will have a working multi-route API with proper HTTP semantics.

From Raw `http` to Express

You saw the built-in http module in F-1:

javascript

const http = require('node:http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World\n');
});

server.listen(3000);

This works, but it has no routing. Every request — regardless of URL or method — hits the same handler. To build a real API you need to route GET /users to one handler, POST /users to another, DELETE /users/:id to a third. You also need to parse JSON bodies, read headers, set response codes properly, and handle errors consistently.

You could implement all of that yourself on top of http. Express already did it — and did it well.

bash

npm install express

Your First Express Server

javascript

// src/index.js
import express from 'express';

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware: parse incoming JSON bodies
app.use(express.json());

// Route: GET /
app.get('/', (req, res) => {
  res.json({ message: 'Hello from Express!' });
});

// Start listening
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

bash

node src/index.js
curl http://localhost:3000/
# {"message":"Hello from Express!"}

The Express API:

express() creates an application instance
app.use(...) adds middleware (runs on every request)
app.get(path, handler) registers a GET route
req — the incoming request object
res — the response object
res.json(data) — sends JSON with Content-Type: application/json and status 200

HTTP Methods and REST Conventions

REST APIs use HTTP methods to express intent:

Method	Meaning	Example
`GET`	Read a resource	`GET /users` — list all users
`POST`	Create a resource	`POST /users` — create a user
`PUT`	Replace a resource entirely	`PUT /users/42` — replace user 42
`PATCH`	Update part of a resource	`PATCH /users/42` — update user 42's email
`DELETE`	Remove a resource	`DELETE /users/42` — delete user 42

Express has a method for each:

javascript

app.get('/users', (req, res) => { /* list users */ });
app.post('/users', (req, res) => { /* create user */ });
app.put('/users/:id', (req, res) => { /* replace user */ });
app.patch('/users/:id', (req, res) => { /* update user */ });
app.delete('/users/:id', (req, res) => { /* delete user */ });

Route Parameters

Route parameters are named placeholders in the URL path, prefixed with :. Express captures them and puts them in req.params.

javascript

// :id is a route parameter
app.get('/users/:id', (req, res) => {
  const { id } = req.params;  // e.g. '42' (always a string)
  res.json({ userId: id });
});

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

bash

curl http://localhost:3000/users/42
# {"userId":"42"}

curl http://localhost:3000/users/42/posts/7
# {"userId":"42","postId":"7"}

Important: route parameters are always strings, even if the URL contains a number. Convert them explicitly:

javascript

app.get('/users/:id', async (req, res) => {
  const id = parseInt(req.params.id, 10);

  if (isNaN(id)) {
    return res.status(400).json({ error: 'id must be a number' });
  }

  const user = await db.findUser(id);
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }

  res.json(user);
});

Query Strings

Query strings are the ?key=value part of a URL. Express parses them automatically into req.query.

javascript

// GET /users?role=admin&active=true&page=2&limit=20
app.get('/users', async (req, res) => {
  const {
    role,
    active,
    page = '1',
    limit = '20'
  } = req.query;

  const pageNum = parseInt(page, 10);
  const limitNum = parseInt(limit, 10);
  const isActive = active === 'true';

  const users = await db.findUsers({ role, active: isActive, pageNum, limitNum });
  res.json(users);
});

bash

curl "http://localhost:3000/users?role=admin&active=true&page=1&limit=10"

Query string values are always strings — convert them as needed.

Request Bodies

For POST, PUT, and PATCH requests, data comes in the request body. With express.json() middleware registered, Express automatically parses JSON bodies into req.body.

javascript

// Middleware registered once at the top — applies to all routes
app.use(express.json());

// POST /users — create a new user
app.post('/users', async (req, res) => {
  const { name, email, role } = req.body;

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

  const newUser = await db.createUser({ name, email, role: role || 'user' });
  res.status(201).json(newUser);  // 201 Created
});

bash

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

# {"id": 1, "name": "Jatin", "email": "jatin@example.com", "role": "user"}

For URL-encoded forms (HTML form submissions):

javascript

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

HTTP Status Codes

Always respond with the appropriate status code. Clients use these to understand what happened.

javascript

// 200 OK — successful GET, PUT, PATCH
res.status(200).json(data);
res.json(data);  // 200 is the default

// 201 Created — successful POST that created a resource
res.status(201).json(newUser);

// 204 No Content — successful DELETE (no body to return)
res.status(204).send();

// 400 Bad Request — client sent invalid data
res.status(400).json({ error: 'email is required' });

// 401 Unauthorized — not authenticated
res.status(401).json({ error: 'Authentication required' });

// 403 Forbidden — authenticated but not authorised
res.status(403).json({ error: 'You do not have permission' });

// 404 Not Found — resource does not exist
res.status(404).json({ error: 'User not found' });

// 409 Conflict — resource already exists (e.g. duplicate email)
res.status(409).json({ error: 'Email already registered' });

// 422 Unprocessable Entity — valid format but fails business rules
res.status(422).json({ error: 'Age must be 18 or over' });

// 500 Internal Server Error — something broke on the server
res.status(500).json({ error: 'Internal server error' });

Middleware

Middleware is the backbone of Express. A middleware function receives (req, res, next) and either:

Responds to the request (ends the chain), or
Calls next() to pass control to the next middleware or route handler

javascript

// Middleware executes in the order it's registered
app.use(express.json());           // 1. Parse JSON body
app.use(requestLogger);            // 2. Log the request
app.use(authenticate);             // 3. Verify auth token
app.get('/users', listUsers);      // 4. Handle the route

Writing a custom middleware

javascript

// Request logger middleware
function requestLogger(req, res, next) {
  const start = Date.now();

  // Override res.json to capture the response status
  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`${req.method} ${req.path} ${res.statusCode} ${duration}ms`);
  });

  next(); // Pass to the next middleware
}

app.use(requestLogger);

Middleware that adds data to the request

javascript

// Add a requestId to every request
import { randomUUID } from 'node:crypto';

function addRequestId(req, res, next) {
  req.id = randomUUID();
  res.setHeader('X-Request-Id', req.id);
  next();
}

app.use(addRequestId);

// Later in a route handler, req.id is available
app.get('/users', (req, res) => {
  console.log('Request ID:', req.id);
  res.json([]);
});

Middleware that can stop the chain

javascript

// Simple API key check
function requireApiKey(req, res, next) {
  const apiKey = req.headers['x-api-key'];

  if (!apiKey || apiKey !== process.env.API_KEY) {
    // Respond here — do NOT call next()
    return res.status(401).json({ error: 'Invalid or missing API key' });
  }

  next(); // Only called if the key is valid
}

// Apply to specific routes only
app.get('/admin/stats', requireApiKey, (req, res) => {
  res.json({ totalUsers: 1500 });
});

Express Router

As your API grows, keeping every route in index.js becomes unmanageable. Use express.Router() to split routes into separate files:

javascript

// src/routes/users.js
import { Router } from 'express';
const router = Router();

router.get('/', async (req, res) => {
  const users = await db.findAll();
  res.json(users);
});

router.get('/:id', async (req, res) => {
  const user = await db.findById(parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'Not found' });
  res.json(user);
});

router.post('/', async (req, res) => {
  const user = await db.create(req.body);
  res.status(201).json(user);
});

router.delete('/:id', async (req, res) => {
  await db.delete(parseInt(req.params.id));
  res.status(204).send();
});

export default router;

javascript

// src/routes/posts.js
import { Router } from 'express';
const router = Router();

router.get('/', async (req, res) => { /* ... */ });
router.post('/', async (req, res) => { /* ... */ });

export default router;

javascript

// src/index.js
import express from 'express';
import usersRouter from './routes/users.js';
import postsRouter from './routes/posts.js';

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

// Mount routers at their base paths
app.use('/users', usersRouter);
app.use('/posts', postsRouter);

// Routes: GET /users, POST /users, DELETE /users/:id
//         GET /posts, POST /posts

app.listen(3000);

Error Handling

Express has a special error-handling middleware signature: four arguments (err, req, res, next). Register it after all routes.

javascript

// Route that might throw
app.get('/users/:id', async (req, res, next) => {
  try {
    const user = await db.findById(req.params.id);
    res.json(user);
  } catch (err) {
    next(err); // Forward error to the error handler
  }
});

// Global error handler — must be last app.use()
app.use((err, req, res, next) => {
  console.error(err.stack);

  // Don't expose internal errors in production
  const message = process.env.NODE_ENV === 'production'
    ? 'Internal server error'
    : err.message;

  res.status(err.statusCode || 500).json({ error: message });
});

We cover a much cleaner error handling pattern — with custom error classes and an async wrapper — in P-4. For now this structure works.

Reading Headers and Setting Response Headers

javascript

app.get('/protected', (req, res) => {
  // Read incoming headers
  const authHeader = req.headers['authorization'];
  const contentType = req.headers['content-type'];
  const userAgent = req.headers['user-agent'];

  // Set response headers
  res.setHeader('X-Custom-Header', 'value');
  res.setHeader('Cache-Control', 'no-store');

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

A Complete Working Example

Here is a minimal in-memory users API that uses everything from this module:

javascript

// src/index.js
import express from 'express';
import { randomUUID } from 'node:crypto';

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

// In-memory "database"
const users = new Map();

// GET /users — list all users
app.get('/users', (req, res) => {
  const { role } = req.query;
  let result = Array.from(users.values());
  if (role) result = result.filter(u => u.role === role);
  res.json(result);
});

// GET /users/:id — get one user
app.get('/users/:id', (req, res) => {
  const user = users.get(req.params.id);
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.json(user);
});

// POST /users — create a user
app.post('/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ error: 'name and email are required' });
  }

  const user = { id: randomUUID(), name, email, role: 'user', createdAt: new Date() };
  users.set(user.id, user);
  res.status(201).json(user);
});

// PATCH /users/:id — update a user
app.patch('/users/:id', (req, res) => {
  const user = users.get(req.params.id);
  if (!user) return res.status(404).json({ error: 'User not found' });

  const updated = { ...user, ...req.body, id: user.id }; // id is immutable
  users.set(user.id, updated);
  res.json(updated);
});

// DELETE /users/:id — delete a user
app.delete('/users/:id', (req, res) => {
  if (!users.has(req.params.id)) {
    return res.status(404).json({ error: 'User not found' });
  }
  users.delete(req.params.id);
  res.status(204).send();
});

// Global error handler
app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ error: 'Internal server error' });
});

app.listen(3000, () => console.log('API running on http://localhost:3000'));

Test it with curl:

bash

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Jatin","email":"jatin@example.com"}'

# List users
curl http://localhost:3000/users

# Get user by id (use the id returned from POST)
curl http://localhost:3000/users/<id>

# Update user
curl -X PATCH http://localhost:3000/users/<id> \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'

# Delete user
curl -X DELETE http://localhost:3000/users/<id>

Summary

Express wraps Node's http module with routing, middleware, and a clean API. Install with npm install express.
Routes are registered with app.get, app.post, app.put, app.patch, app.delete. The path and handler are separate concerns.
Route parameters (/users/:id) are in req.params. Always strings — convert them.
Query strings (?page=1&limit=20) are in req.query. Also always strings.
Request body (POST/PUT/PATCH) is in req.body after registering app.use(express.json()).
Status codes are set with res.status(code). Use them correctly — 201 for creation, 204 for deletion, 404 for not found, 400 for bad input.
Middleware runs in registration order. Call next() to continue, or respond to end the chain.
Routers split routes into files. Mount them with app.use('/prefix', router).
Error handler has four arguments (err, req, res, next) and must be registered last.

Next: connecting to a real database from Node.js — PostgreSQL with node-postgres, parameterized queries, and a first look at Prisma.

Knowledge Check

When accessing a route parameter in Express (e.g., /users/:id), what data type is the parameter req.params.id?

In an Express middleware function, what happens if you neither send a response (e.g., res.json()) nor call next()?

What is the correct function signature for a global error-handling middleware in Express?

Test your knowledge with more question sets

PreviousModule F-5: npm and the Node.js Ecosystem Next Module F-7: Working with Databases from Node.js

Discussion

Join the discussion

Loading comments...

Module F-6 — Building HTTP Servers and REST APIs with Express

From Raw http to Express

Your First Express Server

HTTP Methods and REST Conventions

Route Parameters

Query Strings

Request Bodies

HTTP Status Codes

Middleware

Writing a custom middleware

Middleware that adds data to the request

Middleware that can stop the chain

Express Router

Error Handling

Reading Headers and Setting Response Headers

A Complete Working Example

Summary

Test your knowledge with more question sets

Discussion

From Raw `http` to Express