Writing REST APIs With Express Router: A Complete Walkthrough

Writing REST APIs With Express Router: A Complete Walkthrough

A complete walkthrough of building a REST API with Express Router. We will build a posts API.

Step 1: Set Up the Schema

// models/post.js
const mongoose = require('mongoose');

const postSchema = new mongoose.Schema({
  title: { type: String, required: true, minlength: 3, maxlength: 200 },
  body: { type: String, required: true },
  authorId: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
  tags: [String],
  createdAt: { type: Date, default: Date.now },
  updatedAt: { type: Date, default: Date.now }
}, { timestamps: true });

postSchema.index({ authorId: 1, createdAt: -1 });

module.exports = mongoose.model('Post', postSchema);

Step 2: Write the Controller

// controllers/postController.js
const Post = require('../models/post');
const ApiError = require('../utils/ApiError');
const asyncHandler = require('../utils/asyncHandler');

exports.listPosts = asyncHandler(async (req, res) => {
  const skip = parseInt(req.query.skip) || 0;
  const limit = Math.min(parseInt(req.query.limit) || 20, 100);
  const filter = { authorId: req.user.userId };
  if (req.query.tag) filter.tags = req.query.tag;
  const posts = await Post.find(filter).sort({ createdAt: -1 }).skip(skip).limit(limit).lean();
  const total = await Post.countDocuments(filter);
  res.json({ data: posts, total, skip, limit });
});

exports.createPost = asyncHandler(async (req, res) => {
  const post = await Post.create({ ...req.body, authorId: req.user.userId });
  res.status(201).json(post);
});

exports.getPost = asyncHandler(async (req, res) => {
  const post = await Post.findById(req.params.id).populate('authorId', 'firstName lastName');
  if (!post) throw new ApiError(404, 'Post not found');
  res.json(post);
});

exports.updatePost = asyncHandler(async (req, res) => {
  const post = await Post.findById(req.params.id);
  if (!post) throw new ApiError(404, 'Post not found');
  if (post.authorId.toString() !== req.user.userId) throw new ApiError(403, 'Not authorized');
  Object.assign(post, req.body);
  await post.save();
  res.json(post);
});

exports.deletePost = asyncHandler(async (req, res) => {
  const post = await Post.findById(req.params.id);
  if (!post) throw new ApiError(404, 'Post not found');
  if (post.authorId.toString() !== req.user.userId) throw new ApiError(403, 'Not authorized');
  await post.deleteOne();
  res.status(204).end();
});

Step 3: Write the Router

// routes/posts.js
const express = require('express');
const router = express.Router();
const auth = require('../middlewares/auth');
const validate = require('../middlewares/validate');
const { createPostSchema, updatePostSchema } = require('../validations/post');
const controller = require('../controllers/postController');

router.use(auth);

router.get('/', controller.listPosts);
router.post('/', validate(createPostSchema), controller.createPost);
router.get('/:id', controller.getPost);
router.patch('/:id', validate(updatePostSchema), controller.updatePost);
router.delete('/:id', controller.deletePost);

module.exports = router;

Step 4: Mount the Router

// app.js
app.use('/api/v1/posts', require('./routes/posts'));

Step 5: Write the Validation Schema

// validations/post.js
const { z } = require('zod');

const createPostSchema = z.object({
  title: z.string().min(3).max(200),
  body: z.string().min(1),
  tags: z.array(z.string()).optional()
});

const updatePostSchema = z.object({
  title: z.string().min(3).max(200).optional(),
  body: z.string().min(1).optional(),
  tags: z.array(z.string()).optional()
});

module.exports = { createPostSchema, updatePostSchema };

The Takeaway

Build a REST API with Express Router: define a schema, write a controller with asyncHandler and ApiError, write a router with auth and validation middlewares, mount the router under a path, and write Zod validation schemas. Each file has one job. The router stays thin and declarative.