Handling Routes and HTTP Methods

What decides which handler runs when a request for DELETE /tasks/2 arrives? Two values from the request line do: the method and the path. A route registered with app.delete('/tasks/:id', ...) matches that request, while a route registered with app.get('/tasks/:id', ...) does not, even though its path is the same. Deciding which handler receives a request is called routing, and this lesson builds the complete set of routes that the task API needs.

One Path, Several Methods

An HTTP API usually treats a path as the name of a thing, called a resource, and uses the method to say what to do with it. The path /tasks names the list of tasks, and /tasks/2 names one task. The five methods that an API uses most often each have a fixed meaning:

Express has one method on app for each HTTP method, named after it in lowercase: app.get(), app.post(), app.put(), app.patch(), and app.delete(). Each one takes a path and one or more functions, and the last function is the handler.

The Routes for the List

The two routes for /tasks read the list and add to it:

const express = require('express');

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

const tasks = [
  { id: 1, title: 'Write the README', done: true },
  { id: 2, title: 'Buy milk', done: false },
];
let nextId = 3;

app.get('/tasks', (req, res) => {
  const search = req.query.search;
  if (!search) {
    return res.json(tasks);
  }
  const term = search.toLowerCase();
  res.json(tasks.filter((task) => task.title.toLowerCase().includes(term)));
});

app.post('/tasks', (req, res) => {
  const task = { id: nextId++, title: req.body.title, done: false };
  tasks.push(task);
  res.status(201).location(`/tasks/${task.id}`).json(task);
});

The GET route reads an optional query parameter, so GET /tasks?search=milk returns only [{"id":2,"title":"Buy milk","done":false}]. Query parameters are the usual way to search, filter, and paginate a list, because they modify a request for the same resource instead of naming a different one.

The POST route answers with 201 Created, which tells the client that a new resource exists. The method res.location() sets the Location header to the address of that resource, so the client knows where to find it:

HTTP/1.1 201 Created
Location: /tasks/3
Content-Type: application/json; charset=utf-8

{"id":3,"title":"Call the plumber","done":false}

The route takes new IDs from the counter nextId, not from tasks.length + 1 as earlier lessons did. Once a task can be deleted, the length of the list no longer tells you which IDs are free. After deleting task 1 from a list of two, tasks.length + 1 is 2 again, and the API would create a second task with the ID 2.

The Routes for One Task

The four routes for /tasks/:id all start by finding the task, so a small function does that once:

function findIndex(req) {
  return tasks.findIndex((task) => task.id === Number(req.params.id));
}

app.get('/tasks/:id', (req, res) => {
  const index = findIndex(req);
  if (index === -1) {
    return res.status(404).json({ error: 'Task not found' });
  }
  res.json(tasks[index]);
});

app.put('/tasks/:id', (req, res) => {
  const index = findIndex(req);
  if (index === -1) {
    return res.status(404).json({ error: 'Task not found' });
  }
  const { title, done } = req.body;
  tasks[index] = { id: tasks[index].id, title, done };
  res.json(tasks[index]);
});

app.patch('/tasks/:id', (req, res) => {
  const index = findIndex(req);
  if (index === -1) {
    return res.status(404).json({ error: 'Task not found' });
  }
  const { title, done } = req.body;
  if (title !== undefined) tasks[index].title = title;
  if (done !== undefined) tasks[index].done = done;
  res.json(tasks[index]);
});

app.delete('/tasks/:id', (req, res) => {
  const index = findIndex(req);
  if (index === -1) {
    return res.status(404).json({ error: 'Task not found' });
  }
  tasks.splice(index, 1);
  res.sendStatus(204);
});

The difference between PUT and PATCH shows when the client sends only part of a task. A PATCH /tasks/2 request with the body {"done":true} changes one field and keeps the title. A PUT /tasks/2 request with the same body replaces the whole task, so the title is gone:

PATCH /tasks/2  {"done":true}  -> 200 {"id":2,"title":"Buy milk","done":true}
PUT   /tasks/2  {"done":true}  -> 200 {"id":2,"done":true}

A PUT client must therefore send every field. In a real API, the PUT handler would reject a body with missing fields, and chapter 4 adds that validation. The DELETE route answers with 204 No Content and no body, because nothing is left to return.

Grouping Methods for One Path with app.route()

The four routes above repeat the path /tasks/:id. The method app.route() takes the path once and returns an object on which you chain one handler per method:

app.route('/tasks/:id')
  .get((req, res) => { /* same handler as above */ })
  .put((req, res) => { /* same handler as above */ })
  .patch((req, res) => { /* same handler as above */ })
  .delete((req, res) => { /* same handler as above */ });

The result is the same set of routes. It only removes the repetition, and a misspelled path in one of four copies becomes impossible.

Methods That Express Answers for You

Two methods work without any route of your own. Express answers a HEAD request with the GET route for the same path, and sends the headers of that response without the body. Express also answers an OPTIONS request with an Allow header that lists the methods that the path supports. With the routes of this lesson registered, an OPTIONS /tasks/5 request receives Allow: DELETE, GET, HEAD, PATCH, PUT, and an OPTIONS /tasks request receives Allow: GET, HEAD, POST.

When the path exists but the method does not, as with DELETE /tasks, Express does not send 405 Method Not Allowed. It treats the request like any other request that no route matches, and it sends 404 Not Found with the HTML body Cannot DELETE /tasks.

Routes Are Checked in Order

Express compares a request with the routes in the order in which the code registered them, and the first route whose method and path both match handles the request. Suppose that you add a route for task statistics below the routes for one task:

app.get('/tasks/stats', (req, res) => {
  const done = tasks.filter((task) => task.done).length;
  res.json({ total: tasks.length, done });
});

A GET /tasks/stats request never reaches it. The route GET /tasks/:id comes first, and :id matches any segment, including the word stats. The handler converts 'stats' with Number(), gets NaN, finds no task, and sends {"error":"Task not found"} with the status 404.