Chapter 14: REST API with Sequelize

Bring it all together — build a professional REST API with Express routes, Sequelize models, pagination, filtering, and proper error handling.

CRUD Review

Controllers

Services

Pagination & Filtering

Error Handling

Quiz

CRUD Review

Remember our restaurant? Now we're building the entire kitchen system. The controller is the waiter (takes orders, delivers food). The service is the chef (does the actual cooking/logic). The model is the recipe book (defines what each dish looks like). They work together to handle every customer request.

Here's how CRUD maps to HTTP methods and Sequelize operations:

Operation	HTTP	Route	Sequelize	Restaurant
Create	POST	/api/tasks	Task.create()	Place a new order
Read All	GET	/api/tasks	Task.findAll()	See the full menu
Read One	GET	/api/tasks/:id	Task.findByPk()	Ask about a specific dish
Update	PUT	/api/tasks/:id	task.update()	Change your order
Delete	DELETE	/api/tasks/:id	task.destroy()	Cancel your order

Project Structure

Project — Backend API Structure

backend/
├── config/
│   └── database.js        # Sequelize connection
├── models/
│   ├── User.js            # User model
│   └── Task.js            # Task model
├── services/
│   └── taskService.js     # Business logic (the chef)
├── controllers/
│   └── taskController.js  # Request handling (the waiter)
├── routes/
│   └── taskRoutes.js      # URL mapping (the doors)
├── middleware/
│   ├── auth.js            # Authentication check
│   └── errorHandler.js    # Centralized error handling
├── server.js              # Entry point
├── .env                   # Environment variables
└── package.json

Controllers

The controller is the waiter. It takes the customer's request (req), calls the kitchen (service), and delivers the response (res). The waiter doesn't cook — they just coordinate between the customer and the kitchen.

controllers/taskController.js

const taskService = require('../services/taskService');

// Async handler wrapper (avoids repetitive try/catch)
const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

// GET /api/tasks — Get all tasks
exports.getAllTasks = asyncHandler(async (req, res) => {
  const { page, limit, priority, completed, search } = req.query;

  const result = await taskService.getAllTasks({
    userId: req.user.id,    // From auth middleware
    page: parseInt(page) || 1,
    limit: parseInt(limit) || 10,
    priority,
    completed,
    search,
  });

  res.json(result);
});

// GET /api/tasks/:id — Get one task
exports.getTaskById = asyncHandler(async (req, res) => {
  const task = await taskService.getTaskById(req.params.id, req.user.id);

  if (!task) {
    return res.status(404).json({ message: 'Task not found' });
  }

  res.json(task);
});

// POST /api/tasks — Create a task
exports.createTask = asyncHandler(async (req, res) => {
  const task = await taskService.createTask({
    ...req.body,
    userId: req.user.id,   // Attach the logged-in user's ID
  });

  res.status(201).json(task);
});

// PUT /api/tasks/:id — Update a task
exports.updateTask = asyncHandler(async (req, res) => {
  const task = await taskService.updateTask(
    req.params.id,
    req.user.id,
    req.body
  );

  if (!task) {
    return res.status(404).json({ message: 'Task not found' });
  }

  res.json(task);
});

// DELETE /api/tasks/:id — Delete a task
exports.deleteTask = asyncHandler(async (req, res) => {
  const deleted = await taskService.deleteTask(req.params.id, req.user.id);

  if (!deleted) {
    return res.status(404).json({ message: 'Task not found' });
  }

  res.json({ message: 'Task deleted successfully' });
});

Routes — Connecting URLs to Controllers

routes/taskRoutes.js

const express = require('express');
const router = express.Router();
const taskController = require('../controllers/taskController');
const authenticate = require('../middleware/auth');

// All task routes require authentication
router.use(authenticate);

// CRUD routes
router.get('/',     taskController.getAllTasks);    // GET /api/tasks
router.get('/:id',  taskController.getTaskById);   // GET /api/tasks/42
router.post('/',    taskController.createTask);     // POST /api/tasks
router.put('/:id',  taskController.updateTask);    // PUT /api/tasks/42
router.delete('/:id', taskController.deleteTask);  // DELETE /api/tasks/42

module.exports = router;

Notice the clean separation: Routes just map URLs to controller functions. Controllers extract data from requests and call services. This makes each piece easy to test and modify independently.

Services

The service is the chef. It contains the actual business logic — the "how to cook the dish." The service talks to the database (model) and returns the result to the controller (waiter). The chef doesn't care about the customer (req/res) — they only care about cooking (data operations).

services/taskService.js

const { Op } = require('sequelize');
const Task = require('../models/Task');

// Get all tasks with pagination and filtering
exports.getAllTasks = async ({ userId, page, limit, priority, completed, search }) => {
  const offset = (page - 1) * limit;

  // Build dynamic WHERE clause
  const where = { userId };

  if (priority) {
    where.priority = priority;           // Filter by priority
  }
  if (completed !== undefined) {
    where.completed = completed === 'true'; // Convert string to boolean
  }
  if (search) {
    where.title = { [Op.iLike]: `%${search}%` }; // Case-insensitive search
  }

  const { rows: tasks, count: total } = await Task.findAndCountAll({
    where,
    limit,
    offset,
    order: [['createdAt', 'DESC']],      // Newest first
  });

  return {
    tasks,
    pagination: {
      page,
      limit,
      total,
      totalPages: Math.ceil(total / limit),
    },
  };
};

// Get one task
exports.getTaskById = async (id, userId) => {
  return await Task.findOne({
    where: { id, userId },   // Only find tasks owned by this user
  });
};

// Create a task
exports.createTask = async (taskData) => {
  return await Task.create(taskData);
};

// Update a task
exports.updateTask = async (id, userId, updateData) => {
  const task = await Task.findOne({ where: { id, userId } });
  if (!task) return null;

  await task.update(updateData);
  return task;
};

// Delete a task
exports.deleteTask = async (id, userId) => {
  const task = await Task.findOne({ where: { id, userId } });
  if (!task) return false;

  await task.destroy();
  return true;
};

Always filter by userId! Notice every query includes where: { id, userId }. This ensures users can only access their OWN tasks. Without this check, any user could read/edit/delete anyone's data — a major security hole.

Pagination & Filtering

Imagine a library with 10,000 books. You wouldn't dump all 10,000 on the floor — you'd show them page by page (pagination) and let users search by genre or author (filtering). The same principle applies to APIs — don't send all records at once, let clients request specific pages and filters.

How Pagination Works

Pagination — How It Works

// Client requests: GET /api/tasks?page=2&limit=10
// This means: "Give me tasks 11-20" (page 2, 10 per page)

// The math:
// page 1: offset = 0,  shows items 1-10
// page 2: offset = 10, shows items 11-20
// page 3: offset = 20, shows items 21-30
// Formula: offset = (page - 1) * limit

const { rows: tasks, count: total } = await Task.findAndCountAll({
  where: { userId },
  limit: 10,              // How many per page
  offset: 10,             // Skip the first 10 (page 2)
  order: [['createdAt', 'DESC']],
});

// Response includes pagination metadata:
{
  "tasks": [...],          // The 10 tasks for this page
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 47,           // Total tasks in database
    "totalPages": 5        // Math.ceil(47 / 10) = 5 pages
  }
}

Filtering and Sorting

Sequelize — Filtering & Sorting

const { Op } = require('sequelize');

// ===== COMMON FILTERS =====

// Exact match
await Task.findAll({ where: { priority: 'high' } });

// Multiple conditions (AND)
await Task.findAll({
  where: {
    priority: 'high',
    completed: false,
  },
});

// OR condition
await Task.findAll({
  where: {
    [Op.or]: [
      { priority: 'high' },
      { priority: 'medium' },
    ],
  },
});

// Search (LIKE / case-insensitive)
await Task.findAll({
  where: {
    title: { [Op.iLike]: '%meeting%' },  // Contains "meeting"
  },
});

// Date range
await Task.findAll({
  where: {
    createdAt: {
      [Op.gte]: new Date('2026-01-01'),  // Greater than or equal
      [Op.lte]: new Date('2026-12-31'),  // Less than or equal
    },
  },
});

// ===== SORTING =====
await Task.findAll({
  order: [
    ['priority', 'ASC'],    // Sort by priority ascending
    ['createdAt', 'DESC'],   // Then by date descending
  ],
});

Sequelize Operators Reference

Operator	Meaning	Example
`Op.eq`	Equal	`{ age: { [Op.eq]: 25 } }`
`Op.ne`	Not equal	`{ status: { [Op.ne]: 'deleted' } }`
`Op.gt`	Greater than	`{ age: { [Op.gt]: 18 } }`
`Op.gte`	Greater than or equal	`{ price: { [Op.gte]: 10 } }`
`Op.lt`	Less than	`{ age: { [Op.lt]: 65 } }`
`Op.like`	Pattern match	`{ name: { [Op.like]: '%raj%' } }`
`Op.iLike`	Case-insensitive match	`{ name: { [Op.iLike]: '%raj%' } }`
`Op.in`	In a list	`{ id: { [Op.in]: [1, 2, 3] } }`
`Op.or`	OR condition	`{ [Op.or]: [{...}, {...}] }`

Error Handling

Good error handling is like a good hospital. When something goes wrong, you want clear diagnosis (error type), helpful treatment (error message), and proper records (logging). Bad error handling is like a doctor saying "something is wrong" with no further details — useless!

Custom Error Class

utils/AppError.js — Custom Error Class

class AppError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = true;  // Expected errors we can handle gracefully
  }
}

module.exports = AppError;

// Usage in services:
// throw new AppError('Task not found', 404);
// throw new AppError('You are not authorized', 403);
// throw new AppError('Email already exists', 409);

Centralized Error Handler

middleware/errorHandler.js

const errorHandler = (err, req, res, next) => {
  console.error('Error:', err.message);

  // Sequelize Validation Error
  if (err.name === 'SequelizeValidationError') {
    const messages = err.errors.map(e => e.message);
    return res.status(400).json({
      error: 'Validation Error',
      messages,
    });
  }

  // Sequelize Unique Constraint Error (e.g., duplicate email)
  if (err.name === 'SequelizeUniqueConstraintError') {
    const field = err.errors[0]?.path || 'field';
    return res.status(409).json({
      error: `${field} already exists`,
    });
  }

  // Our custom AppError
  if (err.isOperational) {
    return res.status(err.statusCode).json({
      error: err.message,
    });
  }

  // Unexpected errors (bugs, crashes)
  console.error('Unexpected error:', err.stack);
  res.status(500).json({
    error: 'Something went wrong',
    // Only show details in development
    ...(process.env.NODE_ENV === 'development' && {
      details: err.message,
      stack: err.stack,
    }),
  });
};

module.exports = errorHandler;

// In server.js (MUST be last app.use):
// const errorHandler = require('./middleware/errorHandler');
// app.use(errorHandler);

Error handling best practices:
1. Use custom error classes (AppError) for expected errors
2. Handle Sequelize-specific errors (validation, unique constraint)
3. Never expose stack traces in production
4. Always log errors server-side for debugging
5. Return helpful, specific messages to the client

📝 Chapter 14 Quiz

1. What's the difference between a controller and a service?

Controllers are for GET, services are for POST

Controllers handle req/res, services handle business logic

There is no difference

Services are for frontend, controllers for backend

2. For page 3 with 10 items per page, what is the offset?

3. Which operator performs case-insensitive search in Sequelize?

Op.iLike

Op.search

Op.contains

Op.match

4. Why should service methods always filter by userId?

To make queries faster

To sort the results

It's not necessary, it's optional

To ensure users only access their own data (security)

5. What does Task.findAndCountAll() return?

Just the tasks array

Both the tasks (rows) and total count

Only the count of matching tasks

The first matching task

← Chapter 13: Sequelize ORM Chapter 15: Authentication →