Building a REST API with Express.js — Routes, Middleware and Real Patterns

// server.js — the entry point for our Book Library REST API
// Run: node server.js
// Then visit: http://localhost:3000/api/books

const express = require('express');

const app = express(); // create an Express application instance
const PORT = 3000;

// express.json() is middleware that parses incoming request bodies
// that have Content-Type: application/json. Without this, req.body is undefined.
app.use(express.json());

// In-memory data store — we'll replace this pattern with a real DB later
// but the API shape stays identical, which is the whole point of abstraction
let books = [
  { id: 1, title: 'The Pragmatic Programmer', author: 'Hunt & Thomas', year: 1999 },
  { id: 2, title: 'Clean Code', author: 'Robert C. Martin', year: 2008 },
  { id: 3, title: 'You Don\'t Know JS', author: 'Kyle Simpson', year: 2015 },
];

// GET /api/books — retrieve all books
// REST rule: GET never modifies data, always returns a collection or single resource
app.get('/api/books', (req, res) => {
  res.status(200).json({
    success: true,
    count: books.length,
    data: books,
  });
});

// GET /api/books/:id — retrieve one book by its ID
// :id is a route parameter — Express captures whatever is in that URL segment
app.get('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10); // always parse to a number — URL params are strings
  const book = books.find((b) => b.id === bookId);

  if (!book) {
    // 404 means the resource doesn't exist — not a server error, a client error
    return res.status(404).json({ success: false, message: `Book with id ${bookId} not found` });
  }

  res.status(200).json({ success: true, data: book });
});

// POST /api/books — create a new book
// The client sends book data in the request body as JSON
app.post('/api/books', (req, res) => {
  const { title, author, year } = req.body;

  // Basic validation — never trust client input
  if (!title || !author || !year) {
    return res.status(400).json({
      success: false,
      message: 'title, author, and year are required fields',
    });
  }

  // Generate a simple incrementing ID (a real DB would handle this)
  const newBook = {
    id: books.length > 0 ? Math.max(...books.map((b) => b.id)) + 1 : 1,
    title,
    author,
    year: parseInt(year, 10),
  };

  books.push(newBook);

  // 201 Created — not 200. The resource didn't exist before; now it does.
  res.status(201).json({ success: true, data: newBook });
});

// PUT /api/books/:id — replace/update an existing book
app.put('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book with id ${bookId} not found` });
  }

  const { title, author, year } = req.body;

  // Merge the existing book data with the incoming updates
  books[bookIndex] = { ...books[bookIndex], title, author, year: parseInt(year, 10) };

  res.status(200).json({ success: true, data: books[bookIndex] });
});

// DELETE /api/books/:id — remove a book
app.delete('/api/books/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book with id ${bookId} not found` });
  }

  books.splice(bookIndex, 1); // remove the book from our array

  // 204 No Content — success, but there's nothing to return (the resource is gone)
  res.status(204).send();
});

app.listen(PORT, () => {
  console.log(`Book Library API running on http://localhost:${PORT}`);
});

// middleware.js — custom middleware functions for our Book Library API
// These are pure functions: testable, reusable, and single-purpose

// ─── REQUEST LOGGER ───────────────────────────────────────────────────────────
// Logs every incoming request: method, URL, and response time
// This runs for EVERY request because we'll register it with app.use() at the top
const requestLogger = (req, res, next) => {
  const startTime = Date.now();

  // res.on('finish') fires AFTER the response is sent — so we get accurate timing
  res.on('finish', () => {
    const duration = Date.now() - startTime;
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.originalUrl} — ${res.statusCode} (${duration}ms)`);
  });

  next(); // CRITICAL: without next(), the request just hangs — no response ever sent
};

// ─── API KEY AUTHENTICATION ────────────────────────────────────────────────────
// Checks that the client sent a valid API key in the x-api-key header
// In production you'd validate against a database or use JWT — same pattern, more logic
const requireApiKey = (req, res, next) => {
  const VALID_API_KEY = process.env.API_KEY || 'dev-secret-key-12345';
  const clientKey = req.headers['x-api-key'];

  if (!clientKey) {
    // 401 Unauthorized — the client didn't provide credentials at all
    return res.status(401).json({
      success: false,
      message: 'Missing x-api-key header. Include your API key to access this endpoint.',
    });
  }

  if (clientKey !== VALID_API_KEY) {
    // 403 Forbidden — credentials were provided but they're wrong
    return res.status(403).json({
      success: false,
      message: 'Invalid API key. Check your credentials and try again.',
    });
  }

  // Attach the key to the request object for downstream use if needed
  req.apiKey = clientKey;
  next(); // credentials are valid — continue to the route handler
};

// ─── BOOK BODY VALIDATOR ───────────────────────────────────────────────────────
// Validates that POST and PUT requests have the required book fields
// By extracting this to middleware, our route handlers stay clean
const validateBookBody = (req, res, next) => {
  const { title, author, year } = req.body;
  const errors = [];

  if (!title || typeof title !== 'string' || title.trim() === '') {
    errors.push('title must be a non-empty string');
  }
  if (!author || typeof author !== 'string' || author.trim() === '') {
    errors.push('author must be a non-empty string');
  }
  if (!year || isNaN(parseInt(year, 10)) || parseInt(year, 10) < 1000) {
    errors.push('year must be a valid 4-digit number');
  }

  if (errors.length > 0) {
    // Pass an Error object to next() — this triggers Express's error handler
    const validationError = new Error('Validation failed');
    validationError.statusCode = 400;
    validationError.details = errors;
    return next(validationError); // jumps straight to the error-handling middleware
  }

  next();
};

// ─── GLOBAL ERROR HANDLER ──────────────────────────────────────────────────────
// This MUST have exactly 4 parameters — Express detects it as an error handler by signature
// Register this LAST with app.use() — after all routes
const globalErrorHandler = (err, req, res, next) => {
  console.error(`[ERROR] ${err.message}`, err.stack);

  const statusCode = err.statusCode || 500; // default to 500 if no specific code was set
  const response = {
    success: false,
    message: err.message || 'An unexpected server error occurred',
  };

  // Include validation details if present (avoids leaking stack traces to clients)
  if (err.details) {
    response.errors = err.details;
  }

  res.status(statusCode).json(response);
};

module.exports = { requestLogger, requireApiKey, validateBookBody, globalErrorHandler };

// routes/books.js — all book-related routes live here
// This file knows NOTHING about auth or logging — those are app-level concerns

const express = require('express');
const router = express.Router(); // create a Router instance — not a full app
const { validateBookBody } = require('../middleware');

// Simulated data layer — in a real app this would be a service/repository
// The key point: swapping this to a real DB doesn't change the routes at all
let books = [
  { id: 1, title: 'The Pragmatic Programmer', author: 'Hunt & Thomas', year: 1999 },
  { id: 2, title: 'Clean Code', author: 'Robert C. Martin', year: 2008 },
];

// GET / — maps to GET /api/books when mounted at /api/books
// Notice: the path here is '/', not '/api/books' — the prefix is added at mount time
router.get('/', (req, res) => {
  // req.query lets you read URL query parameters like ?author=Martin
  const { author, year } = req.query;

  let results = [...books];

  if (author) {
    results = results.filter((b) =>
      b.author.toLowerCase().includes(author.toLowerCase())
    );
  }
  if (year) {
    results = results.filter((b) => b.year === parseInt(year, 10));
  }

  res.status(200).json({ success: true, count: results.length, data: results });
});

// GET /:id — maps to GET /api/books/:id
router.get('/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const book = books.find((b) => b.id === bookId);

  if (!book) {
    return res.status(404).json({ success: false, message: `Book ${bookId} not found` });
  }
  res.status(200).json({ success: true, data: book });
});

// POST / — validateBookBody middleware runs BEFORE the route handler
// If validation fails, the route handler never executes — the error bubbles to globalErrorHandler
router.post('/', validateBookBody, (req, res) => {
  const { title, author, year } = req.body;
  const newBook = {
    id: books.length > 0 ? Math.max(...books.map((b) => b.id)) + 1 : 1,
    title: title.trim(),
    author: author.trim(),
    year: parseInt(year, 10),
  };
  books.push(newBook);
  res.status(201).json({ success: true, data: newBook });
});

router.put('/:id', validateBookBody, (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book ${bookId} not found` });
  }

  books[bookIndex] = { id: bookId, ...req.body, year: parseInt(req.body.year, 10) };
  res.status(200).json({ success: true, data: books[bookIndex] });
});

router.delete('/:id', (req, res) => {
  const bookId = parseInt(req.params.id, 10);
  const bookIndex = books.findIndex((b) => b.id === bookId);

  if (bookIndex === -1) {
    return res.status(404).json({ success: false, message: `Book ${bookId} not found` });
  }

  books.splice(bookIndex, 1);
  res.status(204).send();
});

module.exports = router;


// ─── app.js — main application file that wires everything together ─────────────
// (In a real project this would be a separate file)

const appSetup = `
const express = require('express');
const { requestLogger, requireApiKey, globalErrorHandler } = require('./middleware');
const bookRouter = require('./routes/books');

const app = express();

app.use(express.json());         // parse JSON bodies — runs for ALL routes
app.use(requestLogger);          // log every request — runs for ALL routes
app.use(requireApiKey);          // auth gate — runs for ALL routes below this line

// Mount the book router at /api/books
// All routes in bookRouter are now prefixed with /api/books
app.use('/api/books', bookRouter);

// 404 handler — catches any request that didn't match a route above
app.use((req, res) => {
  res.status(404).json({ success: false, message: 'Route not found' });
});

// Error handler — MUST be registered last, MUST have 4 params
app.use(globalErrorHandler);

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

console.log('Route structure:\n', appSetup);