🔌 Building RESTful APIs with Express

What REST Really Means

REST (Representational State Transfer) is an architectural style — a set of constraints for designing networked applications — not a library or a protocol. When an API follows those constraints, we call it "RESTful." The big idea: model your application as a collection of resources (users, products, orders), give each one a stable address (a URL), and manipulate them with the standard verbs the web already provides.

💡 A useful analogy: A RESTful API is a well-run library. Each book is a resource, its shelf location is the URI, and the actions are always the same — browse the catalog (GET), donate a new book (POST), replace a worn copy (PUT), correct a typo in the record (PATCH), or withdraw a title (DELETE). Because the rules never change from shelf to shelf, anyone can use the library without a manual.

REST rests on a handful of constraints. You don't have to memorize the academic list, but two of them shape almost every decision you'll make:

Real-world example: GitHub, Stripe, and Twilio all expose RESTful APIs. GitHub addresses a repository's issues at /repos/:owner/:repo/issues — a noun-based URL you operate on with GET, POST, PATCH, and DELETE. Once you learn the pattern for one resource, every other resource in their API feels familiar.

HTTP Methods & CRUD

The four database operations — Create, Read, Update, Delete — map cleanly onto HTTP methods. This mapping is the heart of REST:

Here's the whole verb set wired up in Express. Notice how each handler does one thing and returns one clear status:

// GET — read a collection
app.get('/api/tasks', (req, res) => {
  res.json(tasks);
});

// GET — read one resource
app.get('/api/tasks/:id', (req, res) => {
  const task = findTaskById(req.params.id);
  if (!task) return res.status(404).json({ error: 'Task not found' });
  res.json(task);
});

// POST — create a resource (201 + the new object)
app.post('/api/tasks', (req, res) => {
  const task = createTask(req.body);
  res.status(201).json(task);
});

// PUT — replace a resource entirely
app.put('/api/tasks/:id', (req, res) => {
  const task = replaceTask(req.params.id, req.body);
  res.json(task);
});

// PATCH — update only the fields sent
app.patch('/api/tasks/:id', (req, res) => {
  const task = updateTask(req.params.id, req.body);
  res.json(task);
});

// DELETE — remove a resource (204, no body)
app.delete('/api/tasks/:id', (req, res) => {
  deleteTask(req.params.id);
  res.status(204).send();
});

PUT vs PATCH: the difference that trips people up

PUT replaces the whole resource — anything you omit is wiped. PATCH merges only the fields you send, leaving the rest untouched. Given a starting task { id: 7, title: "Ship", done: false, priority: "high" }:

// PUT /api/tasks/7  with body { "title": "Ship v2", "done": true }
// Result: { id: 7, title: "Ship v2", done: true, priority: null }
//         ^ priority was dropped because PUT replaces everything

// PATCH /api/tasks/7  with body { "title": "Ship v2", "done": true }
// Result: { id: 7, title: "Ship v2", done: true, priority: "high" }
//         ^ priority survives because PATCH only touches sent fields

Designing Resource URIs

A good URI reads like a location, not a command. The action lives in the HTTP method; the URI only says which resource. Follow a few conventions and your API becomes guessable.

Path parameters vs query parameters

Use path parameters to identify a specific resource, and query parameters to filter, sort, or paginate a collection. The rule of thumb: if removing it would point you at a different thing, it's a path parameter; if it only changes which slice of the same collection you see, it's a query parameter.

// Path parameter identifies ONE task
app.get('/api/tasks/:id', getTaskById);

// Query parameters filter, sort, and paginate the SAME collection
app.get('/api/tasks', (req, res) => {
  const { status, sort = 'createdAt', page = 1, limit = 10 } = req.query;

  let result = tasks;
  if (status) result = result.filter(t => t.status === status);

  result = [...result].sort((a, b) =>
    String(a[sort]).localeCompare(String(b[sort]))
  );

  const start = (Number(page) - 1) * Number(limit);
  const pageItems = result.slice(start, start + Number(limit));

  res.json({
    data: pageItems,
    meta: {
      total: result.length,
      page: Number(page),
      limit: Number(limit),
      pages: Math.ceil(result.length / Number(limit)),
    },
  });
});

💡 Postal analogy: The path parameter is the street address — it uniquely names the destination. Query parameters are the delivery instructions ("leave at back door", "signature required"). They change how you get the result, not which building you're delivering to.

Status Codes That Tell the Truth

The status code is the first thing a client reads. Getting it right means clients (and humans debugging with the network tab) instantly understand what happened. Return the most specific accurate code — not 200 for everything.

app.post('/api/users', (req, res) => {
  // 400 — the request itself is malformed
  if (!req.body.email) {
    return res.status(400).json({ error: 'Email is required' });
  }
  // 409 — a real conflict with existing state
  if (userExists(req.body.email)) {
    return res.status(409).json({ error: 'Email already in use' });
  }
  const user = createUser(req.body);
  // 201 — created, and we hand back the new resource
  res.status(201).json(user);
});

Real-world example: Stripe leans heavily on status codes — 400 for invalid parameters, 401 for bad keys, 402 for failed payments, 429 for rate limiting — each paired with a machine-readable error code. That discipline is a big part of why their API is considered a gold standard.

Structuring an Express API

A single app.js with fifty routes becomes unmaintainable fast. The standard fix is to split concerns: routers declare the URLs, controllers hold the logic, and app.js just wires everything together.

project/
├── app.js                    # wiring: middleware, routes, error handler
├── routes/
│   └── task.routes.js        # URL → controller mapping
├── controllers/
│   └── task.controller.js    # request/response logic
└── middleware/
    └── error-handler.js      # centralized error responses

The router is thin — it only says which controller function handles which URL and method:

// routes/task.routes.js
const express = require('express');
const router = express.Router();
const controller = require('../controllers/task.controller');

router.get('/', controller.getAllTasks);
router.get('/:id', controller.getTaskById);
router.post('/', controller.createTask);
router.put('/:id', controller.replaceTask);
router.patch('/:id', controller.updateTask);
router.delete('/:id', controller.deleteTask);

module.exports = router;

And app.js mounts the router under a base path, adds a catch-all 404, and finishes with the error handler:

// app.js
const express = require('express');
const taskRoutes = require('./routes/task.routes');
const errorHandler = require('./middleware/error-handler');

const app = express();
app.use(express.json());               // parse JSON bodies

app.use('/api/tasks', taskRoutes);     // mount the resource

// 404 for anything unmatched
app.use((req, res) => {
  res.status(404).json({ error: 'Resource not found' });
});

app.use(errorHandler);                 // must be last

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

Worked Example: A Tasks API

Let's put it together. Here's a complete controller for a tasks resource using modern async/await. It assumes a Mongoose-style Task model, but the shape is identical for any data layer.

// controllers/task.controller.js
const Task = require('../models/task.model');

// GET /api/tasks  — list with pagination
exports.getAllTasks = async (req, res, next) => {
  try {
    const page = Number(req.query.page) || 1;
    const limit = Number(req.query.limit) || 20;
    const skip = (page - 1) * limit;

    const [tasks, total] = await Promise.all([
      Task.find().skip(skip).limit(limit),
      Task.countDocuments(),
    ]);

    res.status(200).json({
      data: tasks,
      meta: { page, limit, total, pages: Math.ceil(total / limit) },
    });
  } catch (error) {
    next(error);
  }
};

// GET /api/tasks/:id  — read one
exports.getTaskById = async (req, res, next) => {
  try {
    const task = await Task.findById(req.params.id);
    if (!task) return res.status(404).json({ error: 'Task not found' });
    res.status(200).json({ data: task });
  } catch (error) {
    next(error);
  }
};

// POST /api/tasks  — create
exports.createTask = async (req, res, next) => {
  try {
    const task = await Task.create(req.body);
    res.status(201).json({ data: task });
  } catch (error) {
    next(error);
  }
};

// PUT /api/tasks/:id  — full replace
exports.replaceTask = async (req, res, next) => {
  try {
    const task = await Task.findOneAndReplace(
      { _id: req.params.id },
      req.body,
      { new: true, runValidators: true }
    );
    if (!task) return res.status(404).json({ error: 'Task not found' });
    res.status(200).json({ data: task });
  } catch (error) {
    next(error);
  }
};

// PATCH /api/tasks/:id  — partial update
exports.updateTask = async (req, res, next) => {
  try {
    const task = await Task.findByIdAndUpdate(
      req.params.id,
      { $set: req.body },
      { new: true, runValidators: true }
    );
    if (!task) return res.status(404).json({ error: 'Task not found' });
    res.status(200).json({ data: task });
  } catch (error) {
    next(error);
  }
};

// DELETE /api/tasks/:id  — remove
exports.deleteTask = async (req, res, next) => {
  try {
    const task = await Task.findByIdAndDelete(req.params.id);
    if (!task) return res.status(404).json({ error: 'Task not found' });
    res.status(204).send();
  } catch (error) {
    next(error);
  }
};

{
  "data": [
    { "_id": "665f...", "title": "Write lesson", "done": false },
    { "_id": "665f...", "title": "Review PR", "done": true }
  ],
  "meta": { "page": 1, "limit": 2, "total": 17, "pages": 9 }
}

Every handler follows the same skeleton: do the work, check for "not found", return the right status. That predictability is what makes a REST API pleasant to consume.

Hands-on Exercise

const express = require('express');
const { randomUUID } = require('crypto');

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

let bookmarks = [];

app.get('/api/bookmarks', (req, res) => {
  res.status(200).json({ data: bookmarks });
});

app.get('/api/bookmarks/:id', (req, res) => {
  const bookmark = bookmarks.find(b => b.id === req.params.id);
  if (!bookmark) return res.status(404).json({ error: 'Not found' });
  res.status(200).json({ data: bookmark });
});

app.post('/api/bookmarks', (req, res) => {
  if (!req.body.url) {
    return res.status(400).json({ error: 'url is required' });
  }
  const bookmark = { id: randomUUID(), ...req.body };
  bookmarks.push(bookmark);
  res.status(201).json({ data: bookmark });
});

app.patch('/api/bookmarks/:id', (req, res) => {
  const bookmark = bookmarks.find(b => b.id === req.params.id);
  if (!bookmark) return res.status(404).json({ error: 'Not found' });
  Object.assign(bookmark, req.body);
  res.status(200).json({ data: bookmark });
});

app.delete('/api/bookmarks/:id', (req, res) => {
  const index = bookmarks.findIndex(b => b.id === req.params.id);
  if (index === -1) return res.status(404).json({ error: 'Not found' });
  bookmarks.splice(index, 1);
  res.status(204).send();
});

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

Best Practices

Summary & Quiz

📚 Further Reading

• MDN — HTTP request methods
• MDN — HTTP status codes
• Express — Routing guide

🚀 What's Next?

Your API now accepts requests — but it trusts every byte the client sends. Next we'll add request validation and sanitization so bad or malicious input never reaches your business logic.