Creating Routes and Handling Requests with Express

mkdir inventory-api && cd inventory-api
npm init -y
npm install express
npm install -D @types/express typescript

import express, { Request, Response, NextFunction } from 'express';

const catalogServer = express();
const PORT = process.env.PORT || 8080;

// Middleware: Parse incoming JSON payloads
catalogServer.use(express.json());

// Middleware: Parse URL-encoded bodies (form data)
catalogServer.use(express.urlencoded({ extended: true }));

// Health Check Endpoint
catalogServer.get('/health', (req: Request, res: Response) => {
  res.status(200).json({
    status: 'operational',
    uptime: process.uptime(),
    timestamp: new Date().toISOString()
  });
});

catalogServer.listen(PORT, () => {
  console.log(`Inventory API listening on port ${PORT}`);
});

// Static Route
catalogServer.get('/catalog', (req: Request, res: Response) => {
  res.json({ items: ['SKU-001', 'SKU-002'], total: 2 });
});

// Dynamic Route with Parameter
catalogServer.get('/catalog/:skuCode', (req: Request, res: Response) => {
  const { skuCode } = req.params;
  // Simulate database lookup
  res.json({ sku: skuCode, stock: 42, location: 'Warehouse-A' });
});

ss extracts the value from the URL segment and populates req.params. This approach is safer and more readable than regex-based parsing.

4. Query Parameter Handling

Query parameters are optional key-value pairs appended to the URL. Express automatically parses these into the req.query object.

catalogServer.get('/catalog/search', (req: Request, res: Response) => {
  const { category, minPrice, maxPrice } = req.query;
  
  const filters: Record<string, string | number> = {};
  if (category) filters.category = category as string;
  if (minPrice) filters.minPrice = Number(minPrice);
  if (maxPrice) filters.maxPrice = Number(maxPrice);

  res.json({ filters, results: [] });
});

Best Practice: Always validate and cast query parameters. Express parses all query values as strings; numeric comparisons require explicit conversion.

5. POST Requests and Body Validation

Creating resources requires handling the request body. Express populates req.body when the appropriate middleware is active.

catalogServer.post('/catalog/items', (req: Request, res: Response) => {
  const { name, price, category } = req.body;

  // Validation Logic
  if (!name || typeof price !== 'number' || price <= 0) {
    return res.status(400).json({
      error: 'Validation failed',
      details: 'Name is required; price must be a positive number.'
    });
  }

  const newItem = {
    id: crypto.randomUUID(),
    name,
    price,
    category: category || 'general',
    createdAt: new Date().toISOString()
  };

  res.status(201).json({ message: 'Item created', data: newItem });
});

Architecture Decision: Validation is performed immediately upon entry to the handler. Failing fast with a 400 Bad Request prevents invalid data from propagating to downstream services or databases. Using crypto.randomUUID() ensures unique identifiers without external dependencies.

6. Modular Routing with express.Router

For production applications, routes should be organized into modules. The Router class creates isolated route handlers that can be mounted at specific paths.

// routes/inventory.ts
import { Router, Request, Response } from 'express';

const inventoryRouter = Router();

inventoryRouter.get('/', (req: Request, res: Response) => {
  res.json({ endpoint: 'Inventory List' });
});

inventoryRouter.post('/', (req: Request, res: Response) => {
  res.status(201).json({ endpoint: 'Create Inventory Item' });
});

export { inventoryRouter };

// server.ts
import { inventoryRouter } from './routes/inventory';

// Mount router at /api/v1/inventory
catalogServer.use('/api/v1/inventory', inventoryRouter);

Rationale: Modular routing improves maintainability by separating concerns. It allows teams to work on different API segments independently and simplifies versioning strategies.

Pitfall Guide

1. Missing Body Parser Middleware

Explanation: Forgetting to register express.json() results in req.body being undefined. Developers often spend time debugging handlers that appear to receive empty payloads. Fix: Always include app.use(express.json()) near the top of the middleware stack, before route definitions.

2. Route Order Conflicts

Explanation: Defining a dynamic route before a static route can cause unintended matches. For example, /catalog/:id defined before /catalog/new will intercept requests intended for the static path. Fix: Define specific static routes before parameterized routes. Express evaluates routes sequentially.

3. Unhandled Asynchronous Errors

Explanation: If an async handler throws an error, Express will not catch it automatically, potentially crashing the process or leaving the request hanging. Fix: Wrap async handlers in error-catching utilities or use a global error-handling middleware. Avoid try/catch duplication by creating a higher-order function:

const asyncHandler = (fn: Function) => (req: Request, res: Response, next: NextFunction) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

4. Blocking the Event Loop

Explanation: Performing CPU-intensive operations (e.g., image processing, complex calculations) directly in route handlers blocks the single-threaded event loop, degrading performance for all concurrent requests. Fix: Offload heavy tasks to worker threads, message queues, or external services. Keep route handlers lightweight and I/O bound.

5. Inconsistent Response Formats

Explanation: Mixing res.send(), res.json(), and res.end() across endpoints leads to unpredictable client behavior and complicates frontend integration. Fix: Standardize on res.json() for API responses. Use res.status() to set HTTP codes explicitly. Define a response envelope interface for consistency.

6. Security Header Omissions

Explanation: Default Express configurations lack security headers, leaving applications vulnerable to common attacks like XSS or clickjacking. Fix: Integrate helmet middleware to automatically set secure HTTP headers. Add cors middleware to control cross-origin access.

7. Ignoring Validation Libraries

Explanation: Manual validation logic becomes unwieldy as schemas grow. It is error-prone and difficult to maintain. Fix: Adopt validation libraries like zod or joi. These provide schema definition, type inference, and runtime validation with clear error messages.

Production Bundle

Action Checklist

• Initialize project with npm init and install express and @types/express.
• Configure tsconfig.json with strict: true and esModuleInterop: true.
• Register express.json() and express.urlencoded() middleware early in the stack.
• Implement a /health endpoint for load balancer and monitoring integration.
• Structure routes using express.Router for modularity and versioning.
• Add global error-handling middleware to catch unhandled exceptions.
• Integrate helmet and cors for baseline security.
• Use a validation library (e.g., zod) for request body and query validation.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Rapid Prototyping / MVP	Express.js	Extensive ecosystem, low learning curve, fast development.	Low initial cost; moderate scaling cost.
High-Throughput Microservice	Fastify	Superior performance, lower latency, schema-based validation.	Higher learning curve; better resource efficiency.
Enterprise Monolith	Express.js + TypeScript	Mature tooling, strong typing, large talent pool.	Moderate infrastructure cost; high maintainability.
Learning / Protocol Study	Raw Node.js http	Deep understanding of HTTP mechanics and streams.	High development time; not suitable for production.

Configuration Template

Copy this template to establish a production-ready server structure.

// src/server.ts
import express, { Request, Response, NextFunction } from 'express';
import helmet from 'helmet';
import cors from 'cors';
import { inventoryRouter } from './routes/inventory';

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

// Security & Parsing Middleware
app.use(helmet());
app.use(cors());
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Routes
app.use('/api/v1/inventory', inventoryRouter);

// 404 Handler
app.use((req: Request, res: Response) => {
  res.status(404).json({ error: 'Resource not found' });
});

// Global Error Handler
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal server error' });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Quick Start Guide

1. Create Project Directory:

   mkdir express-production-api && cd express-production-api
   

2. Initialize and Install Dependencies:

   npm init -y
   npm install express helmet cors
   npm install -D @types/express @types/node typescript ts-node
   

3. Create tsconfig.json:

   {
     "compilerOptions": {
       "target": "ES2020",
       "module": "commonjs",
       "strict": true,
       "outDir": "./dist",
       "rootDir": "./src",
       "esModuleInterop": true
     }
   }
   

4. Create src/server.ts with the Configuration Template above.
5. Run the Server:

   npx ts-node src/server.ts
   

   The API will be accessible at http://localhost:3000. Verify with curl http://localhost:3000/health.