Creating RESTful APIs with Express.js (Advanced Guide)

RESTful APIs are the backbone of modern web applications. With Express.js, building powerful and scalable APIs becomes much easier. While beginners can get started quickly, mastering advanced RESTful API patterns is essential for real-world projects where security, performance, and maintainability matter.

This guide dives deep into advanced techniques for building RESTful APIs using Express.js.

Table of Contents

1. RESTful APIs Recap
2. Express Router Best Practices
3. Controller-Service Architecture
4. Middleware Chaining & Error Handling
5. Route Parameter Validation with Joi/Zod
6. Authentication & Authorization (JWT)
7. API Versioning
8. Pagination, Filtering, and Sorting
9. Rate Limiting & Security Headers
10. Testing Your API (Jest & Supertest)
11. Documentation with Swagger
12. Conclusion

1. RESTful APIs Recap

A RESTful API uses HTTP methods to perform CRUD operations:

• GET – Read data
• POST – Create data
• PUT/PATCH – Update data
• DELETE – Remove data

Each resource (e.g., /users, /posts) should be logically mapped.

2. Express Router Best Practices

Use separate router files for each resource to keep things modular.

routes/user.routes.js

const express = require('express');
const router = express.Router();
const userController = require('../controllers/user.controller');

router.get('/', userController.getAllUsers);
router.post('/', userController.createUser);
router.get('/:id', userController.getUserById);
router.put('/:id', userController.updateUser);
router.delete('/:id', userController.deleteUser);

module.exports = router;

In your main app file:

const userRoutes = require('./routes/user.routes');
app.use('/api/users', userRoutes);

3. Controller-Service Architecture

Separate business logic from controllers.

controllers/user.controller.js

const userService = require('../services/user.service');

exports.getAllUsers = async (req, res, next) => {
  try {
    const users = await userService.getAll();
    res.json(users);
  } catch (err) {
    next(err);
  }
};

services/user.service.js

const User = require('../models/user.model');

exports.getAll = async () => {
  return await User.find();
};

4. Middleware Chaining & Error Handling

Create reusable middlewares and a centralized error handler.

middlewares/error.middleware.js

module.exports = (err, req, res, next) => {
  console.error(err.stack);
  res.status(err.status || 500).json({ error: err.message });
};

Use in app:

app.use(require('./middlewares/error.middleware'));

5. Route Parameter Validation

Use Joi or Zod to validate request bodies, params, and queries.

middlewares/validate.middleware.js

const Joi = require('joi');

const userSchema = Joi.object({
  name: Joi.string().min(3).required(),
  email: Joi.string().email().required()
});

module.exports = (req, res, next) => {
  const { error } = userSchema.validate(req.body);
  if (error) return res.status(400).json({ error: error.details[0].message });
  next();
};

Apply in route:

router.post('/', validateUser, userController.createUser);

6. Authentication & Authorization (JWT)

Secure your routes using JWT tokens.

middlewares/auth.middleware.js

const jwt = require('jsonwebtoken');

module.exports = (req, res, next) => {
  const token = req.headers.authorization?.split(" ")[1];
  if (!token) return res.sendStatus(401);
  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch (e) {
    res.sendStatus(403);
  }
};

Use on protected routes:

router.get('/profile', authMiddleware, userController.getProfile);

7. API Versioning

Maintain multiple API versions without breaking existing clients.

app.use('/api/v1/users', v1UserRoutes);
app.use('/api/v2/users', v2UserRoutes);

This helps in rolling out features or refactors without disrupting users.

8. Pagination, Filtering, and Sorting

Offer clients more flexibility using query parameters.

controllers/user.controller.js

exports.getAllUsers = async (req, res) => {
  const { page = 1, limit = 10, sort = 'name' } = req.query;
  const users = await User.find()
    .sort(sort)
    .skip((page - 1) * limit)
    .limit(Number(limit));
  res.json(users);
};

9. Rate Limiting & Security Headers

Prevent abuse and attacks.

const rateLimit = require('express-rate-limit');
const helmet = require('helmet');

app.use(helmet());

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100
});
app.use(limiter);

10. Testing Your API (Jest & Supertest)

Use Jest and Supertest to write automated tests.

const request = require('supertest');
const app = require('../app');

describe('GET /api/users', () => {
  it('should return all users', async () => {
    const res = await request(app).get('/api/users');
    expect(res.statusCode).toBe(200);
    expect(res.body).toBeInstanceOf(Array);
  });
});

11. Documentation with Swagger

Auto-generate docs with Swagger using swagger-jsdoc and swagger-ui-express.

const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: "3.0.0",
    info: { title: "User API", version: "1.0.0" }
  },
  apis: ["./routes/*.js"],
};

const specs = swaggerJsdoc(options);
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs));

12. Conclusion

Building RESTful APIs with Express.js goes far beyond basic routing. By implementing structured architecture, secure authentication, request validation, and proper middleware patterns, you can deliver production-grade APIs that are scalable, secure, and easy to maintain.

By mastering these advanced techniques, your Express.js APIs will be ready for the demands of enterprise-level applications and real-world traffic.