express

Express.js HTTP APIs AI Skill Guide

Overview & Engine Architecture

Express is a minimal Node HTTP framework built around middleware chains and routers. Request flows top-to-bottom; the first matching route wins unless next() continues. Agents keep middleware ordered correctly (parsers before handlers, error middleware last), wrap async routes so rejections reach the error handler, and validate input before business logic.

req -> middleware... -> router -> handler
                              \-> next(err) -> error middleware -> res

When to use this skill

• Building REST/JSON APIs on Node
• Splitting apps into domain routers
• Fixing hanging requests from unhandled async errors
• Adding auth, logging, and rate-limit middleware

Operational directives

1. Mount express.json() / urlencoded only where needed; cap body size.
2. Put four-arg error middleware (err, req, res, next) after all routes.
3. Wrap async handlers or use a helper so rejected promises call next(err).
4. Use Router() per domain; keep app.js / server.js thin.
5. Never trust req.body shape - validate with zod/joi or similar.

App sketch

import express from "express";

const app = express();
app.use(express.json({ limit: "100kb" }));

const items = express.Router();

items.get("/", (_req, res) => {
  res.json([{ id: 1, sku: "A" }]);
});

items.post("/", (req, res, next) => {
  Promise.resolve()
    .then(() => {
      const sku = req.body?.sku;
      if (typeof sku !== "string" || !sku) {
        const err = new Error("sku required");
        err.status = 400;
        throw err;
      }
      res.status(201).json({ id: 2, sku });
    })
    .catch(next);
});

app.use("/items", items);

app.use((err, _req, res, _next) => {
  const status = err.status ?? 500;
  res.status(status).json({ error: err.message ?? "internal error" });
});

app.listen(3000);

Commands

npm install express
node --watch src/server.js
NODE_ENV=production node src/server.js