Node.js REST API · Foundations

Controllers

A controller is the translator between HTTP and your business logic: it reads the request, calls a service and turns the result into a response. Keeping controllers thin makes the whole API easier to test and change.

Beginner 7 min Lesson 5 of 25

Before you start:Routing

0/25 in Node.js REST API

On this page · 7 min · Beginner

Interview questions

Learning objectives#

Explain what belongs in a controller (and what does not)
Create controllers with injected services
Map service results to HTTP status codes
Unit-test a controller with fake req/res objects

Explanation#

A controller does three things: read input (params, query, body, req.user), call one service method, send the response with the right status. Business rules (“a course needs lessons before publishing”) live in the service.

Use factories: createCourseController({ courseService }) returns an object of handler functions. The dependencies are passed in, so tests can pass fakes and production can pass the real MySQL-backed service.

Services report outcomes either by throwing typed errors (handled by the error middleware) or by returning results such as { error: "not_found" }. Pick one style per project; this lesson shows results, the Error Handling lesson shows exceptions.

Composition root: one place (app.js) creates repositories, services and controllers and wires them into routers.

Because handlers are plain functions, you can test them by calling them with a fake req and res — no network or port needed.

Syntax#

JavaScript Illustrative

1export function createCourseController({ courseService }) {
2  return {
3    async get(req, res) {
4      const course = await courseService.get(Number(req.params.id));
5      if (!course) return res.status(404).json({ error: 'Course not found' });
6      res.json(course);
7    },
8  };
9}

Code example: A course controller with an injected service#

JavaScriptcontrollers.js Illustrative

1import express from 'express';
2

3// services/courses.service.js — business rules, no HTTP
4function createCourseService(store) {
5  return {
6    list: ({ level }) => store.filter(c => !level || c.level === level),
7    get: id => store.find(c => c.id === id) ?? null,
8    publish(id) {
9      const course = this.get(id);
10      if (!course) return { error: 'not_found' };
11      if (course.lessons === 0) return { error: 'no_lessons' };
12      course.published = true;
13      return { course };
14    },
15  };
16}
17

18// controllers/courses.controller.js — HTTP in, HTTP out
19function createCourseController({ courseService }) {
20  return {
21    list(req, res) {
22      res.json(courseService.list({ level: req.query.level }));
23    },
24    get(req, res) {
25      const course = courseService.get(Number(req.params.id));
26      if (!course) return res.status(404).json({ error: 'Course not found' });
27      res.json(course);
28    },
29    publish(req, res) {
30      const { course, error } = courseService.publish(Number(req.params.id));
31      if (error === 'not_found') return res.status(404).json({ error: 'Course not found' });
32      if (error === 'no_lessons') return res.status(422).json({ error: 'Add at least one lesson before publishing' });
33      res.json(course);
34    },
35  };
36}
37

38// app.js — composition root
39const store = [
40  { id: 1, title: 'Node.js REST APIs', level: 'beginner', lessons: 12, published: false },
41  { id: 2, title: 'Advanced Express', level: 'advanced', lessons: 0, published: false },
42];
43const controller = createCourseController({ courseService: createCourseService(store) });
44

45// 1. Unit test: call the controller directly with a fake response
46const fakeRes = {
47  statusCode: 200,
48  status(code) { this.statusCode = code; return this; },
49  json(body) { this.body = body; return this; },
50};
51controller.publish({ params: { id: '2' } }, fakeRes);
52console.log('unit test:', fakeRes.statusCode, fakeRes.body.error);
53

54// 2. The same controller, mounted in Express
55const router = express.Router();
56router.get('/', controller.list);
57router.get('/:id', controller.get);
58router.post('/:id/publish', controller.publish);
59

60const app = express();
61app.use('/api/courses', router);
62

63const server = app.listen(3103, async () => {
64  const base = 'http://localhost:3103/api/courses';
65  for (const [method, path] of [['GET', '?level=advanced'], ['POST', '/1/publish'], ['POST', '/2/publish'], ['GET', '/9']]) {
66    const r = await fetch(base + path, { method });
67    console.log(method.padEnd(4), path.padEnd(16), r.status, await r.text());
68  }
69  server.close();
70});

Expected output

unit test: 422 Add at least one lesson before publishing
GET  ?level=advanced  200 [{"id":2,"title":"Advanced Express","level":"advanced","lessons":0,"published":false}]
POST /1/publish       200 {"id":1,"title":"Node.js REST APIs","level":"beginner","lessons":12,"published":true}
POST /2/publish       422 {"error":"Add at least one lesson before publishing"}
GET  /9               404 {"error":"Course not found"}

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

The service owns the rule “no lessons → cannot publish” and knows nothing about HTTP.
The controller maps service outcomes to 200, 404 and 422.
The composition root creates the service and injects it into the controller.
A fake res object lets us unit-test the controller without starting a server.
The same controller functions are mounted on an Express router unchanged.

Real-world use case#

LearnHub’s CoursesController is tested with a fake service in milliseconds, while the service is tested with an in-memory repository. Only a handful of slower integration tests use a real MySQL database.

Common mistakes#

Fat controllers

SQL, validation, business rules and formatting in one handler make reuse (e.g. from a CLI or queue worker) impossible.

Services that know about req/res

A service taking req or calling res.status cannot be reused or tested on its own. Pass plain values in, return plain values out.

Importing singletons everywhere

Controllers that import a global db cannot be tested with fakes. Inject dependencies.

Best practices#

Thin controllers: input → service → response
Inject dependencies through factories
One composition root
Unit-test controllers with fakes

Remember this#

Controller = HTTP translator. Service = rules.

Factories + injection = easy fakes.

One service call per handler is a good smell.

Practice exercise#

Your task: Add an archive(req, res) controller method that calls courseService.archive(id) and returns 404 for not_found, 409 for already_archived, and 200 with the course otherwise. Test it with a fake service and fake res.

Need a hint?

The fake service can be an object literal: { archive: () => ({ error: "already_archived" }) }.

Show solution

JavaScript Illustrative

1function createCourseController({ courseService }) {
2  return {
3    archive(req, res) {
4      const { course, error } = courseService.archive(Number(req.params.id));
5      if (error === 'not_found') return res.status(404).json({ error: 'Course not found' });
6      if (error === 'already_archived') return res.status(409).json({ error: 'Course is already archived' });
7      res.json(course);
8    },
9  };
10}
11

12const fakeService = { archive: () => ({ error: 'already_archived' }) };
13const res = { status(c) { this.code = c; return this; }, json(b) { this.body = b; return this; } };
14createCourseController({ courseService: fakeService }).archive({ params: { id: '1' } }, res);
15console.log(res.code, res.body.error);   // 409 Course is already archived

Mini quiz#

Controllers quizMultiple choice Question 1 of 3

Where should the rule “a course needs at least one lesson to be published” live?

Score so far: 0/0

Want more? Practise all Node.js REST API MCQs · Node.js REST API interview questions

My notes#

Saved in this browser.

Progress is saved in this browser. Sign in to sync.

On this page

Related tutorials

Interview questions

Learning objectives#

Explanation#

Syntax#

Code example: A course controller with an injected service#

Step-by-step explanation#

Real-world use case#

Common mistakes#

Best practices#

Remember this#

Practice exercise#

Mini quiz#

Related topics#

My notes#