Scalable API Design

Scalable API Design in Node.js

Designing a scalable API in Node.js means creating a backend architecture that is modular, secure, performant, and easy to maintain as your application grows. In this guide, we’ll cover best practices and examples of building scalable REST APIs using Express.js, MongoDB (with Mongoose), and supporting tools.

1. Folder Structure for Scalability

A clean and scalable folder structure separates concerns and enables team collaboration.

project-root/
├── config/
│   └── db.js
├── controllers/
│   └── user.controller.js
├── middlewares/
│   └── auth.js
├── models/
│   └── user.model.js
├── routes/
│   └── v1/
│       └── user.routes.js
├── services/
│   └── user.service.js
├── utils/
│   └── logger.js
├── validations/
│   └── user.validation.js
├── app.js
├── server.js
└── .env

2. Modular Route Handling

Each route is encapsulated in its own module.

routes/v1/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);

module.exports = router;

controllers/user.controller.js

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

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

exports.createUser = async (req, res) => {
  const user = await userService.create(req.body);
  res.status(201).json(user);
};

3. API Versioning

Versioning ensures backward compatibility and smooth transition across updates.

app.js

const express = require('express');
const app = express();

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

4. Environment Configuration

npm install dotenv

.env

PORT=5000
DB_URI=mongodb://localhost:27017/scalable_api

config/db.js

const mongoose = require('mongoose');

const connectDB = async () => {
  try {
    await mongoose.connect(process.env.DB_URI, {
      useNewUrlParser: true,
      useUnifiedTopology: true,
    });
    console.log('MongoDB connected');
  } catch (err) {
    console.error('DB Connection Error:', err.message);
    process.exit(1);
  }
};

module.exports = connectDB;

5. Request Validation with Joi

npm install joi

validations/user.validation.js

const Joi = require('joi');

exports.createUser = Joi.object({
  name: Joi.string().required(),
  email: Joi.string().email().required()
});

6. Middleware for Central Error Handling

middlewares/error.js

const errorHandler = (err, req, res, next) => {
  console.error(err);
  res.status(500).json({ error: err.message });
};

module.exports = errorHandler;

7. Pagination Support

controllers/user.controller.js

exports.getAllUsers = async (req, res) => {
  const { page = 1, limit = 10 } = req.query;
  const users = await userService.getAllPaginated(page, limit);
  res.json(users);
};

services/user.service.js

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

exports.getAllPaginated = async (page, limit) => {
  const skip = (page - 1) * limit;
  return await User.find().skip(skip).limit(Number(limit));
};

8. Rate Limiting to Prevent Abuse

npm install express-rate-limit

app.js

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

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100
});

app.use(limiter);

9. Logging with Morgan

npm install morgan

const morgan = require('morgan');
app.use(morgan('combined'));

10. Secure Headers with Helmet

npm install helmet

const helmet = require('helmet');
app.use(helmet());

11. Unit Testing with Jest and Supertest

npm install --save-dev jest supertest

tests/user.test.js

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

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

12. Swagger API Documentation

npm install swagger-jsdoc swagger-ui-express

docs/swagger.js

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

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

const specs = swaggerJsdoc(options);

module.exports = { swaggerUi, specs };

app.js (add docs route)

const { swaggerUi, specs } = require('./docs/swagger');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

13. Deployment Readiness

• Use Docker for containerization
• Use PM2 for process management
• Ensure CORS settings are secure
• Minimize attack surface with proper input validation and escaping

Scalable API design requires careful planning of structure, modularity, and tools. Following the principles of separation of concerns, validation, documentation, and performance optimization ensures that your Node.js API remains robust and easy to maintain as it grows. The combination of Express, Mongoose, and supporting libraries gives you the flexibility to develop fast while staying enterprise-grade.