Node.js REST API · Delivery

Complete REST API Project

Time to put the whole track together. This project is the LearnHub API in one runnable file: users register and log in, instructors manage their own courses, students enrol, admins moderate — validated, secured and consistent.

Advanced 12 min Lesson 25 of 25

Before you start:Role-Based Authorization Pagination Error Handling

0/25 in Node.js REST API

On this page · 12 min · Advanced

Interview questions

Learning objectives#

Combine routing, validation, errors, auth and authorization in one API
Enforce roles and ownership on real endpoints
Return paginated lists and Problem Details errors
Verify the whole flow end to end

Explanation#

Structure (one file here, split into folders in a real project): config → errors → data → schemas → middleware → routers → createApp → end-to-end run.

Auth: register (students only — instructors are created by admins), login with bcrypt and a dummy hash, 15-minute Bearer tokens, rate-limited login.

Courses: public list with pagination and level filter; create for instructors/admins; update for the owner or an admin; delete for admins. router.param loads the course once.

Enrollments: students enrol once (second time → 409). Course DTOs include the instructor name and enrolment count — never raw rows.

Every error is application/problem+json; validation problems add an errors array. Swap the in-memory data for the mysql2 repositories from earlier lessons to go to production.

Code example: LearnHub API: the complete project#

JavaScriptlearnhub-api.js Illustrative

1import express from 'express';
2import helmet from 'helmet';
3import cors from 'cors';
4import { rateLimit } from 'express-rate-limit';
5import bcrypt from 'bcryptjs';
6import jwt from 'jsonwebtoken';
7import { z } from 'zod';
8

9// ── config.js ──
10const config = { jwtSecret: process.env.JWT_SECRET ?? 'dev-only-secret-change-me-32-chars-long', corsOrigins: ['http://localhost:5173'], bcryptCost: 10 };
11

12// ── errors.js ──
13class ApiError extends Error {
14  constructor(status, title, detail, errors) { super(detail); Object.assign(this, { status, title, detail, errors }); }
15}
16const notFound = what => new ApiError(404, 'Not Found', `${what} was not found`);
17const forbidden = detail => new ApiError(403, 'Forbidden', detail);
18

19// ── data (swap for mysql2 repositories) ──
20const db = { users: [], courses: [], enrollments: [] };
21const DUMMY_HASH = await bcrypt.hash('not-a-real-password', config.bcryptCost);
22db.users.push(
23  { id: 1, email: 'admin@learnhub.example', name: 'Admin', role: 'admin', passwordHash: await bcrypt.hash('admin-pass-2026!', config.bcryptCost) },
24  { id: 2, email: 'ravi@learnhub.example', name: 'Ravi', role: 'instructor', passwordHash: await bcrypt.hash('ravi-teaches-node', config.bcryptCost) },
25);
26

27// ── schemas.js ──
28const Email = z.string().trim().toLowerCase().email();
29const Registration = z.strictObject({ email: Email, password: z.string().min(12).max(72), name: z.string().trim().min(2).max(60) });
30const Login = z.object({ email: Email, password: z.string().min(1) });
31const Level = z.enum(['beginner', 'intermediate', 'advanced']);
32const CourseInput = z.strictObject({ title: z.string().trim().min(3).max(120), level: Level, price: z.number().int().min(0) });
33const ListQuery = z.object({ page: z.coerce.number().int().min(1).default(1), pageSize: z.coerce.number().int().min(1).max(50).default(10), level: Level.optional() });
34

35function parse(schema, value) {
36  const result = schema.safeParse(value ?? {});
37  if (result.success) return result.data;
38  throw new ApiError(400, 'Validation failed', 'One or more fields are invalid',
39    result.error.issues.map(i => ({ field: i.path.join('.') || null, message: i.message })));
40}
41

42// ── middleware ──
43function authenticate(req, res, next) {
44  const [scheme, token] = (req.get('authorization') ?? '').split(' ');
45  try {
46    if (scheme !== 'Bearer') throw new Error('no token');
47    req.user = jwt.verify(token, config.jwtSecret, { algorithms: ['HS256'] });
48    req.user.id = Number(req.user.sub);
49    next();
50  } catch {
51    next(new ApiError(401, 'Unauthorized', 'Authentication required'));
52  }
53}
54const requireRole = (...roles) => (req, res, next) =>
55  roles.includes(req.user.role) ? next() : next(forbidden(`Requires role: ${roles.join(' or ')}`));
56

57// ── routes/auth.js ──
58const auth = express.Router();
59auth.post('/register', async (req, res) => {
60  const { email, password, name } = parse(Registration, req.body);
61  if (db.users.some(u => u.email === email)) throw new ApiError(409, 'Conflict', 'Email already registered');
62  const user = { id: db.users.length + 1, email, name, role: 'student', passwordHash: await bcrypt.hash(password, config.bcryptCost) };
63  db.users.push(user);
64  res.status(201).json({ id: user.id, email, name, role: user.role });
65});
66auth.post('/login', rateLimit({ windowMs: 15 * 60_000, limit: 10, standardHeaders: 'draft-7', legacyHeaders: false }), async (req, res) => {
67  const { email, password } = parse(Login, req.body);
68  const user = db.users.find(u => u.email === email);
69  const ok = await bcrypt.compare(password, user?.passwordHash ?? DUMMY_HASH);
70  if (!user || !ok) throw new ApiError(401, 'Unauthorized', 'Invalid email or password');
71  const accessToken = jwt.sign({ sub: String(user.id), role: user.role }, config.jwtSecret, { expiresIn: '15m' });
72  res.json({ accessToken, tokenType: 'Bearer', expiresIn: 900 });
73});
74

75// ── routes/courses.js ──
76const toCourse = c => ({
77  id: c.id, title: c.title, level: c.level, price: c.price,
78  instructor: db.users.find(u => u.id === c.instructorId).name,
79  enrolled: db.enrollments.filter(e => e.courseId === c.id).length,
80});
81const courses = express.Router();
82courses.param('id', (req, res, next, id) => {
83  req.course = db.courses.find(c => c.id === Number(id));
84  req.course ? next() : next(notFound(`Course ${id}`));
85});
86courses.get('/', (req, res) => {
87  const { page, pageSize, level } = parse(ListQuery, req.query);
88  const all = db.courses.filter(c => !level || c.level === level);
89  res.json({ data: all.slice((page - 1) * pageSize, page * pageSize).map(toCourse), meta: { page, pageSize, total: all.length } });
90});
91courses.get('/:id', (req, res) => res.json(toCourse(req.course)));
92courses.post('/', authenticate, requireRole('instructor', 'admin'), (req, res) => {
93  const course = { id: db.courses.length + 1, ...parse(CourseInput, req.body), instructorId: req.user.id };
94  db.courses.push(course);
95  res.status(201).location(`/api/v1/courses/${course.id}`).json(toCourse(course));
96});
97courses.patch('/:id', authenticate, (req, res) => {
98  if (req.course.instructorId !== req.user.id && req.user.role !== 'admin') throw forbidden('You can only edit your own courses');
99  Object.assign(req.course, parse(CourseInput.partial(), req.body));
100  res.json(toCourse(req.course));
101});
102courses.delete('/:id', authenticate, requireRole('admin'), (req, res) => {
103  db.courses.splice(db.courses.indexOf(req.course), 1);
104  res.sendStatus(204);
105});
106courses.post('/:id/enrollments', authenticate, requireRole('student'), (req, res) => {
107  if (db.enrollments.some(e => e.courseId === req.course.id && e.userId === req.user.id)) throw new ApiError(409, 'Conflict', 'Already enrolled in this course');
108  db.enrollments.push({ courseId: req.course.id, userId: req.user.id });
109  res.status(201).json({ courseId: req.course.id, userId: req.user.id });
110});
111

112// ── app.js ──
113function createApp() {
114  const app = express();
115  app.use(helmet(), cors({ origin: config.corsOrigins, credentials: true }), express.json({ limit: '10kb' }));
116  app.get('/health', (req, res) => res.json({ status: 'ok' }));
117  const v1 = express.Router();
118  v1.use('/auth', auth);
119  v1.use('/courses', courses);
120  app.use('/api/v1', v1);
121  app.use((req, res, next) => next(notFound(`Route ${req.method} ${req.path}`)));
122  app.use((err, req, res, next) => {
123    const status = err instanceof ApiError ? err.status : err.type === 'entity.parse.failed' ? 400 : 500;
124    if (status === 500) console.error(err);
125    res.status(status).type('application/problem+json').json({
126      type: 'about:blank',
127      title: err.title ?? (status === 400 ? 'Bad Request' : 'Internal Server Error'),
128      status,
129      detail: status === 500 ? 'Something went wrong' : err.detail ?? err.message,
130      ...(err.errors && { errors: err.errors }),
131      instance: req.originalUrl,
132    });
133  });
134  return app;
135}
136

137// ── End-to-end run ──
138const server = createApp().listen(3119, async () => {
139  const base = 'http://localhost:3119/api/v1';
140  async function step(label, method, path, { token, body } = {}) {
141    const r = await fetch(base + path, {
142      method,
143      headers: { 'Content-Type': 'application/json', ...(token && { Authorization: `Bearer ${token}` }) },
144      body: body && JSON.stringify(body),
145    });
146    const data = r.status === 204 ? null : await r.json();
147    let summary = data?.accessToken ? 'Bearer token issued' : data?.errors ? `${data.detail}: ${data.errors.map(e => e.field).join(', ')}` : data?.detail ?? JSON.stringify(data);
148    if (r.status === 204) summary = '(no body)';
149    console.log(`${label.padEnd(30)} ${r.status} ${summary}`);
150    return data;
151  }
152

153  await step('Asha registers', 'POST', '/auth/register', { body: { email: 'asha@example.com', password: 'asha-learns-2026', name: 'Asha' } });
154  const asha = (await step('Asha logs in', 'POST', '/auth/login', { body: { email: 'ASHA@example.com', password: 'asha-learns-2026' } })).accessToken;
155  const ravi = (await step('Ravi (instructor) logs in', 'POST', '/auth/login', { body: { email: 'ravi@learnhub.example', password: 'ravi-teaches-node' } })).accessToken;
156  const admin = (await step('Admin logs in', 'POST', '/auth/login', { body: { email: 'admin@learnhub.example', password: 'admin-pass-2026!' } })).accessToken;
157

158  await step('Ravi creates a course', 'POST', '/courses', { token: ravi, body: { title: 'Node.js REST APIs', level: 'beginner', price: 499 } });
159  await step('Ravi sends invalid data', 'POST', '/courses', { token: ravi, body: { title: 'JS', level: 'expert', price: -1 } });
160  await step('Asha tries to create', 'POST', '/courses', { token: asha, body: { title: 'My course', level: 'beginner', price: 0 } });
161  await step('Create without a token', 'POST', '/courses', { body: { title: 'Anonymous', level: 'beginner', price: 0 } });
162  await step('Asha enrols', 'POST', '/courses/1/enrollments', { token: asha });
163  await step('Asha enrols again', 'POST', '/courses/1/enrollments', { token: asha });
164  await step('Asha edits Ravi’s course', 'PATCH', '/courses/1', { token: asha, body: { price: 1 } });
165  await step('Ravi lowers the price', 'PATCH', '/courses/1', { token: ravi, body: { price: 399 } });
166  await step('List beginner courses', 'GET', '/courses?level=beginner&pageSize=5');
167  await step('Get a missing course', 'GET', '/courses/42');
168  await step('Ravi tries to delete', 'DELETE', '/courses/1', { token: ravi });
169  await step('Admin deletes it', 'DELETE', '/courses/1', { token: admin });
170  server.close();
171});

Expected output

Asha registers                 201 {"id":3,"email":"asha@example.com","name":"Asha","role":"student"}
Asha logs in                   200 Bearer token issued
Ravi (instructor) logs in      200 Bearer token issued
Admin logs in                  200 Bearer token issued
Ravi creates a course          201 {"id":1,"title":"Node.js REST APIs","level":"beginner","price":499,"instructor":"Ravi","enrolled":0}
Ravi sends invalid data        400 One or more fields are invalid: title, level, price
Asha tries to create           403 Requires role: instructor or admin
Create without a token         401 Authentication required
Asha enrols                    201 {"courseId":1,"userId":3}
Asha enrols again              409 Already enrolled in this course
Asha edits Ravi’s course       403 You can only edit your own courses
Ravi lowers the price          200 {"id":1,"title":"Node.js REST APIs","level":"beginner","price":399,"instructor":"Ravi","enrolled":1}
List beginner courses          200 {"data":[{"id":1,"title":"Node.js REST APIs","level":"beginner","price":399,"instructor":"Ravi","enrolled":1}],"meta":{"page":1,"pageSize":5,"total":1}}
Get a missing course           404 Course 42 was not found
Ravi tries to delete           403 Requires role: admin
Admin deletes it               204 (no body)

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#

Seeded admin and instructor accounts exist; public registration always creates students.
Login normalises the email (ASHA@example.com works) and issues a Bearer token.
Validation, roles (403), missing tokens (401) and duplicates (409) all come back as Problem Details.
Ownership: Asha cannot edit Ravi’s course; Ravi can.
Lists are paginated DTOs with the instructor name and enrolment count; only an admin may delete.

Real-world use case#

This is the back end for the React integration lesson and the Angular CRUD project. Replace db with the MySQL repositories, move each section into its folder, add the logging middleware and the Dockerfile, and it is ready to deploy.

Common mistakes#

Letting users choose their role at registration

{ "role": "admin" } in a sign-up body is a classic privilege escalation. strictObject rejects it here; roles are assigned by admins.

Authorizing before loading

Ownership checks need the course; router.param loads it first, then the handler compares owners.

Shipping the dev secret

The fallback JWT secret is for local runs only. Production must fail to start without JWT_SECRET (see the config lessons).

Best practices#

Layers: config, errors, data, schemas, middleware, routes
Roles + ownership on every write
Problem Details everywhere
An end-to-end script that exercises the whole flow

Remember this#

authenticate → requireRole → ownership check → validate → act.

401 no token · 403 not allowed · 409 duplicate · 404 missing.

DTOs out, schemas in.

Practice exercise#

Your task: Add GET /api/v1/me/enrollments that returns the signed-in student’s courses as DTOs.

Need a hint?

Mount a me router with authenticate, filter db.enrollments by req.user.id and map each to toCourse(course).

Show solution

JavaScript Illustrative

1// const me = express.Router();
2// me.get('/enrollments', authenticate, (req, res) => {
3//   const courseIds = db.enrollments.filter(e => e.userId === req.user.id).map(e => e.courseId);
4//   res.json(db.courses.filter(c => courseIds.includes(c.id)).map(toCourse));
5// });
6// v1.use('/me', me);
7console.log('GET /api/v1/me/enrollments → 200 [ { id, title, level, price, instructor, enrolled } ]');

Mini quiz#

Complete REST API Project quizMultiple choice Question 1 of 3

Why does registration ignore (reject) a role field?

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#

Code example: LearnHub API: the complete project#

Step-by-step explanation#

Real-world use case#

Common mistakes#

Best practices#

Remember this#

Practice exercise#

Mini quiz#

Related topics#

My notes#