🗂️ Weekend Project: Build a RESTful Task-Management API

The Goal

Build a backend service that manages tasks over HTTP. A client — a browser, a mobile app, or just curl — sends a request like POST /api/tasks with a JSON body, and your API creates the task, stores it, and answers with 201 Created and the new resource. Ask for GET /api/tasks?status=open&sort=-dueDate&page=2 and it returns the second page of open tasks, newest-due first, plus metadata telling the client how many pages exist. Send garbage and it answers 422 with a precise list of what's wrong — never a stack trace, never a crash.

Every request that reaches your API travels the same pipeline: body parsing, then route matching, then validation, then the controller, and — if anything throws — straight to one error handler at the end. Hold this picture in your head; each stage below builds one band of it.

The discipline that makes this maintainable is separation of concerns. Routes only say which URL maps to which handler. Controllers hold the request/response logic. The data layer knows how tasks are stored — and only it does. When a bug appears, its layer is obvious: a wrong URL is a route problem, a wrong status code is a controller problem, a lost task is a store problem.

Prerequisites

This is the Week 7 capstone, so it leans on the whole "Backend with Node & Express" week. Before you start, make sure you're comfortable with:

You'll need Node.js 18 or newer (check with node --version), a code editor, and a terminal. That's it — no database, no framework beyond Express. If you have Postman, Insomnia, or the VS Code REST Client extension you can use them, but plain curl is all this guide assumes.

Required Features Checklist

These are the non-negotiables. Every one is achievable with Express, express-validator, and the standard library — no database required. Tick each off as you go.

Project Structure

Backend Express apps are organized by role: routes, controllers, middleware, data, and errors each get a folder under src/. This is the layout you'll build. It looks like a lot for one resource, but it's exactly the shape a ten-resource API keeps — you're learning the pattern, not just the app.

task-api/
├── package.json
├── .gitignore              <-- ignores node_modules, data/*.json
└── src/
    ├── server.js           <-- entry point: starts app.listen()
    ├── app.js              <-- builds the Express app (no listen)
    ├── routes/
    │   └── taskRoutes.js   <-- express.Router(): URL → controller
    ├── controllers/
    │   └── taskController.js  <-- request/response logic per action
    ├── middleware/
    │   ├── validateTask.js    <-- express-validator rule chains
    │   ├── validationResult.js<-- turns validator errors into ValidationError
    │   └── errorHandler.js    <-- the one 4-arg error middleware + 404
    ├── data/
    │   └── taskStore.js    <-- the repository (in-memory or JSON file)
    ├── models/
    │   └── task.js         <-- factory that shapes a Task object
    └── errors/
        └── AppError.js     <-- AppError + NotFoundError, ValidationError, …

Stage 1 — Scaffold the Express App

Start the project and install the two runtime dependencies plus nodemon for auto-restart during development.

# Create and enter the project
mkdir task-api && cd task-api
npm init -y

# Runtime deps: Express + input validation
npm install express express-validator

# Dev dep: auto-restart on save
npm install --save-dev nodemon

Add scripts to package.json so you can run the server two ways. (Setting "type": "commonjs" is the Node default; we use require throughout for familiarity.)

{
  "name": "task-api",
  "version": "1.0.0",
  "main": "src/server.js",
  "type": "commonjs",
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js"
  }
}

Now build the app. Modern Express has built-in body parsers — you no longer need the old body-parser package. express.json() reads a JSON request body and hands it to you as req.body; without it, req.body is undefined and every POST silently fails.

// src/app.js — builds the app but does NOT start it
const express = require('express');
const taskRoutes = require('./routes/taskRoutes');
const { notFoundHandler, errorHandler } = require('./middleware/errorHandler');

function createApp() {
  const app = express();

  // --- Global middleware ---
  app.use(express.json());                          // parse JSON bodies → req.body
  app.use(express.urlencoded({ extended: true }));  // parse form bodies too

  // --- Health check / API root ---
  app.get('/', (req, res) => {
    res.json({ name: 'Task Management API', version: '1.0.0', resource: '/api/tasks' });
  });

  // --- Feature routes (mounted under a resource prefix) ---
  app.use('/api/tasks', taskRoutes);

  // --- 404 for anything unmatched, then the ONE error handler ---
  app.use(notFoundHandler);   // must come AFTER all routes
  app.use(errorHandler);      // must be LAST, and take 4 args

  return app;
}

module.exports = createApp;

// src/server.js — the only file that opens a port
const createApp = require('./app');

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

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

Stage 2 — Task Model & Data Layer

Before routes, decide what a Task is and where it lives. Two small files: a model that shapes a task consistently, and a store (repository) that owns all reads and writes. The rest of the app talks to the store and never touches the raw array or file — so if you later swap in a real database, only this one file changes.

The Task model

A factory function gives every task the same shape and sensible defaults, and stamps timestamps. Using crypto.randomUUID() (built into Node 18+) means no uuid package.

// src/models/task.js
const { randomUUID } = require('crypto');

const PRIORITIES = ['low', 'medium', 'high'];
const STATUSES = ['open', 'in-progress', 'done'];

// Build a fully-formed task from partial input, filling defaults.
function makeTask(input) {
  const now = new Date().toISOString();
  return {
    id: randomUUID(),
    title: input.title.trim(),
    description: input.description?.trim() || '',
    status: input.status || 'open',
    priority: input.priority || 'medium',
    dueDate: input.dueDate || null,
    createdAt: now,
    updatedAt: now,
  };
}

module.exports = { makeTask, PRIORITIES, STATUSES };

The data store (repository)

Here's the in-memory version — an array plus async methods. Every method is async even though nothing awaits yet; that keeps the interface identical to a real database, so upgrading later is a drop-in. Each lookup throws a NotFoundError when the id is missing, so controllers never have to check for undefined.

// src/data/taskStore.js — in-memory repository
const { makeTask } = require('../models/task');
const { NotFoundError } = require('../errors/AppError');

let tasks = [];   // the entire "database" — one array

const taskStore = {
  // Return a shallow copy so callers can't mutate our array by reference.
  async findAll() {
    return [...tasks];
  },

  async findById(id) {
    const task = tasks.find((t) => t.id === id);
    if (!task) throw new NotFoundError(`Task ${id} not found`);
    return task;
  },

  async create(data) {
    const task = makeTask(data);
    tasks.push(task);
    return task;
  },

  async update(id, changes) {
    const task = await this.findById(id);          // throws if missing
    Object.assign(task, changes, { updatedAt: new Date().toISOString() });
    return task;
  },

  async remove(id) {
    const index = tasks.findIndex((t) => t.id === id);
    if (index === -1) throw new NotFoundError(`Task ${id} not found`);
    tasks.splice(index, 1);
  },
};

module.exports = taskStore;

// src/data/taskStore.js — JSON-file variant (same interface, so nothing else changes)
const fs = require('fs/promises');
const path = require('path');
const { makeTask } = require('../models/task');
const { NotFoundError } = require('../errors/AppError');

const FILE = path.join(__dirname, 'tasks.json');

async function load() {
  try {
    return JSON.parse(await fs.readFile(FILE, 'utf8'));
  } catch (err) {
    if (err.code === 'ENOENT') return [];   // no file yet → empty list
    throw err;
  }
}
const save = (tasks) => fs.writeFile(FILE, JSON.stringify(tasks, null, 2));

const taskStore = {
  async findAll() { return load(); },
  async findById(id) {
    const task = (await load()).find((t) => t.id === id);
    if (!task) throw new NotFoundError(`Task ${id} not found`);
    return task;
  },
  async create(data) {
    const tasks = await load();
    const task = makeTask(data);
    tasks.push(task);
    await save(tasks);
    return task;
  },
  // update() and remove() follow the same load → change → save pattern.
};

module.exports = taskStore;

Stage 3 — CRUD Routes & Controllers

Now the heart of the API. First the route table, which maps each URL + verb to a controller and slots the validation middleware in front of the writes. This is a classic REST resource router.

// src/routes/taskRoutes.js
const express = require('express');
const controller = require('../controllers/taskController');
const { validateCreateTask, validateUpdateTask } = require('../middleware/validateTask');
const { runValidation } = require('../middleware/validationResult');

const router = express.Router();

router
  .route('/')
  .get(controller.list)                                       // GET    /api/tasks
  .post(validateCreateTask, runValidation, controller.create); // POST   /api/tasks

router
  .route('/:id')
  .get(controller.getOne)                                     // GET    /api/tasks/:id
  .put(validateUpdateTask, runValidation, controller.update)  // PUT    /api/tasks/:id
  .delete(controller.remove);                                 // DELETE /api/tasks/:id

module.exports = router;

The asyncHandler wrapper

Every controller is async, and an error thrown inside an async function does not automatically reach Express's error middleware — you'd have to write try/catch with next(err) in all five handlers. A tiny wrapper removes that boilerplate: it catches any rejected promise and forwards it to next. Write it once, wrap every handler.

// src/middleware/asyncHandler.js
// Wrap an async route handler so any thrown/rejected error goes to next().
const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

module.exports = asyncHandler;

The controllers

Each controller is small and does one job: read what it needs off req, call the store, and send a response with the correct status. Notice there's no try/catch — asyncHandler handles it, and a missing task throws NotFoundError inside the store, which sails straight to the error middleware.

// src/controllers/taskController.js
const taskStore = require('../data/taskStore');
const asyncHandler = require('../middleware/asyncHandler');
const { paginateAndSort } = require('../data/query');   // built in Stage 6

// GET /api/tasks  — list with pagination, filter, and sort (Stage 6)
exports.list = asyncHandler(async (req, res) => {
  const all = await taskStore.findAll();
  const result = paginateAndSort(all, req.query);
  res.status(200).json(result);   // { data: [...], pagination: {...} }
});

// GET /api/tasks/:id  — read one
exports.getOne = asyncHandler(async (req, res) => {
  const task = await taskStore.findById(req.params.id);   // throws NotFoundError
  res.status(200).json({ data: task });
});

// POST /api/tasks  — create
exports.create = asyncHandler(async (req, res) => {
  const task = await taskStore.create(req.body);
  res.status(201).json({ data: task });    // 201 Created for a new resource
});

// PUT /api/tasks/:id  — update
exports.update = asyncHandler(async (req, res) => {
  const task = await taskStore.update(req.params.id, req.body);
  res.status(200).json({ data: task });
});

// DELETE /api/tasks/:id  — delete
exports.remove = asyncHandler(async (req, res) => {
  await taskStore.remove(req.params.id);   // throws NotFoundError if missing
  res.status(204).send();                  // 204 No Content — empty body
});

Stage 4 — Validation Middleware

Never trust the request body. Before a task reaches the store, express-validator checks it against a set of rules. A rule chain is just an array of middleware you drop into the route before the controller — you already wired them into taskRoutes.js in Stage 3.

// src/middleware/validateTask.js
const { body } = require('express-validator');
const { PRIORITIES, STATUSES } = require('../models/task');

// Rules for creating a task: title required, the rest optional but typed.
const validateCreateTask = [
  body('title')
    .trim()
    .notEmpty().withMessage('title is required')
    .isLength({ max: 100 }).withMessage('title must be 100 characters or fewer'),
  body('description')
    .optional().trim()
    .isLength({ max: 500 }).withMessage('description must be 500 characters or fewer'),
  body('status')
    .optional()
    .isIn(STATUSES).withMessage(`status must be one of: ${STATUSES.join(', ')}`),
  body('priority')
    .optional()
    .isIn(PRIORITIES).withMessage(`priority must be one of: ${PRIORITIES.join(', ')}`),
  body('dueDate')
    .optional({ nullable: true })
    .isISO8601().withMessage('dueDate must be an ISO-8601 date string'),
];

// Rules for updating: same fields, but title is now optional too.
// (Reuse everything except title from the create rules, then add an optional title.)
const validateUpdateTask = [
  body('title')
    .optional().trim()
    .notEmpty().withMessage('title cannot be empty')
    .isLength({ max: 100 }).withMessage('title must be 100 characters or fewer'),
  ...validateCreateTask.slice(1),   // description, status, priority, dueDate rules
];

module.exports = { validateCreateTask, validateUpdateTask };

The rule chains only record problems onto the request. A second, shared middleware reads that record and, if it's non-empty, throws your custom ValidationError — so validation failures flow through the exact same error handler as everything else.

// src/middleware/validationResult.js
const { validationResult } = require('express-validator');
const { ValidationError } = require('../errors/AppError');

// Collect any validation errors and hand them to the error middleware.
function runValidation(req, res, next) {
  const result = validationResult(req);
  if (result.isEmpty()) return next();     // all good, continue

  // Normalize into a clean, consistent shape for the client.
  const details = result.array().map((e) => ({ field: e.path, message: e.msg }));
  next(new ValidationError('Validation failed', details));
}

module.exports = { runValidation };

Stage 5 — Centralized Error Handling

Here's the payoff for all that structure. Instead of formatting errors in every controller, you define a small family of custom error classes that each carry an HTTP status, and one error middleware that turns any of them into a clean JSON response. Throw an error anywhere — a route, a controller, the store — and it lands here.

// src/errors/AppError.js
// Base class: every operational error carries an HTTP status code.
class AppError extends Error {
  constructor(message, statusCode = 500) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = true;               // "expected" error, not a bug
    Error.captureStackTrace(this, this.constructor);
  }
}

class BadRequestError extends AppError {
  constructor(message = 'Bad request') { super(message, 400); }
}

class NotFoundError extends AppError {
  constructor(message = 'Resource not found') { super(message, 404); }
}

class ValidationError extends AppError {
  constructor(message = 'Validation failed', details = []) {
    super(message, 422);
    this.details = details;                  // per-field error list
  }
}

module.exports = { AppError, BadRequestError, NotFoundError, ValidationError };

The error middleware is the last thing mounted in app.js, and its four-argument signature (err, req, res, next) is how Express knows it handles errors. It reads err.statusCode (defaulting to 500), attaches field details when present, and hides stack traces outside development.

// src/middleware/errorHandler.js
const { AppError, NotFoundError } = require('../errors/AppError');

// Any request that matched no route ends up here → a 404 error.
function notFoundHandler(req, res, next) {
  next(new NotFoundError(`Route ${req.method} ${req.originalUrl} not found`));
}

// THE central error handler. Must take 4 args and be mounted last.
function errorHandler(err, req, res, next) {   // eslint-disable-line no-unused-vars
  // Unknown/unexpected errors default to 500 and a safe message.
  const isKnown = err instanceof AppError;
  const statusCode = isKnown ? err.statusCode : 500;

  const body = {
    error: {
      message: isKnown ? err.message : 'Internal Server Error',
      status: statusCode,
    },
  };

  if (err.details) body.error.details = err.details;         // validation fields
  if (process.env.NODE_ENV !== 'production') body.error.stack = err.stack;

  // Log server-side; only 5xx are true surprises worth shouting about.
  if (statusCode >= 500) console.error(err);

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

module.exports = { notFoundHandler, errorHandler };

Stage 6 — Pagination, Filter & Sort

A list endpoint that returns everything falls over the moment there are ten thousand tasks. Real APIs let the client ask for a slice: filter to narrow the set, sort to order it, and paginate to take one page at a time. All three are read from the query string on GET /api/tasks, e.g. ?status=open&priority=high&sort=-dueDate&page=2&limit=20.

Keep the logic in one small, testable helper so the controller stays clean:

// src/data/query.js
// Apply filter → sort → paginate to an array, driven by req.query.
function paginateAndSort(items, query) {
  let result = [...items];

  // --- 1. FILTER: exact-match on known fields, if present ---
  for (const field of ['status', 'priority']) {
    if (query[field]) {
      result = result.filter((t) => t[field] === query[field]);
    }
  }

  // --- 2. SORT: "?sort=dueDate" ascending, "?sort=-dueDate" descending ---
  if (query.sort) {
    const desc = query.sort.startsWith('-');
    const key = desc ? query.sort.slice(1) : query.sort;
    result.sort((a, b) => {
      if (a[key] === b[key]) return 0;
      const cmp = a[key] > b[key] ? 1 : -1;
      return desc ? -cmp : cmp;
    });
  }

  // --- 3. PAGINATE: clamp page/limit to safe numbers, then slice ---
  const page = Math.max(1, parseInt(query.page, 10) || 1);
  const limit = Math.min(100, Math.max(1, parseInt(query.limit, 10) || 20));
  const total = result.length;
  const totalPages = Math.max(1, Math.ceil(total / limit));
  const start = (page - 1) * limit;
  const data = result.slice(start, start + limit);

  return {
    data,
    pagination: { page, limit, total, totalPages, hasNext: page < totalPages },
  };
}

module.exports = { paginateAndSort };

Because controller.list already calls this helper and returns its result, the response now carries both the page of tasks and the metadata a client needs to build "next / previous" controls:

{
  "data": [
    { "id": "a1b2…", "title": "Ship the API", "status": "open", "priority": "high", "dueDate": "2026-08-05", "createdAt": "…", "updatedAt": "…" }
  ],
  "pagination": { "page": 2, "limit": 20, "total": 47, "totalPages": 3, "hasNext": true }
}

Stage 7 — Test With curl

Fire up the server with npm run dev, then drive every endpoint from a second terminal. Watch not just the JSON but the status code — that's the real contract. Add -i to any command to print response headers including the status line.

# Create a task → expect 201 Created
curl -i -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Ship the API","priority":"high","dueDate":"2026-08-05T00:00:00.000Z"}'

# List tasks, filtered + sorted + paginated → expect 200 OK
curl "http://localhost:3000/api/tasks?status=open&sort=-dueDate&page=1&limit=10"

# Read one task (paste a real id from the create response) → 200 or 404
curl http://localhost:3000/api/tasks/PASTE_ID_HERE

# Update a task → expect 200 OK
curl -X PUT http://localhost:3000/api/tasks/PASTE_ID_HERE \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

# Delete a task → expect 204 No Content (empty body)
curl -i -X DELETE http://localhost:3000/api/tasks/PASTE_ID_HERE

Now prove the unhappy paths, which are where beginner APIs fall apart:

# Missing title → expect 422 with a per-field details array
curl -i -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"priority":"high"}'

# Unknown id → expect 404 Not Found
curl -i http://localhost:3000/api/tasks/does-not-exist

# Bad route → expect 404 from the notFoundHandler
curl -i http://localhost:3000/api/nope

The 422 response should look like this — a stable shape your future front end can rely on:

{
  "error": {
    "message": "Validation failed",
    "status": 422,
    "details": [
      { "field": "title", "message": "title is required" }
    ]
  }
}

### Create a task
POST http://localhost:3000/api/tasks
Content-Type: application/json

{ "title": "Ship the API", "priority": "high" }

### List open tasks, newest due first
GET http://localhost:3000/api/tasks?status=open&sort=-dueDate

Stretch Goals

Finished the required build with time to spare? Level it up — pick whichever excites you; none are needed to pass the rubric.

API-key auth starter

Here's how little code the auth preview takes — one middleware, mounted only on the routes you want to protect:

// src/middleware/requireApiKey.js
const { AppError } = require('../errors/AppError');

class UnauthorizedError extends AppError {
  constructor(message = 'Unauthorized') { super(message, 401); }
}

function requireApiKey(req, res, next) {
  if (req.get('x-api-key') !== process.env.API_KEY) {
    return next(new UnauthorizedError('Valid x-api-key header required'));
  }
  next();
}

module.exports = { requireApiKey, UnauthorizedError };
// In taskRoutes.js: router.post('/', requireApiKey, validateCreateTask, runValidation, controller.create);

Because it throws an AppError subclass, it plugs into your existing error handler with zero changes — the same reward, one more time, for centralizing errors early.

Self-Check Rubric

Before you call this done, grade yourself against the rubric. Aim to answer "yes" to everything in the first two columns — the stretch column is bonus.

Summary

This project is proof that Week 7 stuck. You crossed from calling other people's servers to running your own, and you did it the way professionals do: resources over verbs, validation you can trust, errors funneled to one place, and a list endpoint that scales. The moves you practiced here — separate the layers, wrap your async, centralize your errors, never trust the query string — are the everyday grammar of production backends.

📚 Additional Resources

• Express — Routing guide
• Express — Error handling
• express-validator — Documentation
• MDN — HTTP response status codes
• MDN — HTTP request methods

🚀 What's Next?

Your API works — but every task lives in an array (or a JSON file) that a single restart can wipe, and there's no querying beyond a linear scan. Real apps need a real database. Week 8 begins exactly there: the next lesson, Relational vs NoSQL Databases, weighs tables-and-rows (SQL, like PostgreSQL) against documents-and-collections (NoSQL, like MongoDB), so you can choose the right home for your data before you wire it into this very API.