Node.js Scalable REST API Architecture

server setup

Create a server/index.js file and add this code to it. This function creates a server object and preserves it using a javascript property called a closure. link

Import the server in the main index.js file of your rest-api and pass the config into it.

const server = require('./server')();
const config = require('./configs');
const db = require('./configs/db');

server.create(config, db);
server.start(); // this kickstarts your server.

you should use nodemon for development purposes. It monitors your code changes and restarts the server with the recent updates.

Follow the given directory structure. It consists of dirs like, routes, api-versions, controllers, services and configs.

This is made this way to make the node-app scalable i.e. when supposedly developing a newer version on top of the older version, it makes it easy to integrate it with the existing up and running server.

Then, there is the configs dir to store all the required configs of the node-app. to reflect changes to every variable, incase needed.

api version setup

The routes dir contains apis/v1.js, which contains all the existing routes for the version1 of the node-rest-api, the controllers of which are inside controllers/v1/*.js. They make the development process less messy and easier.

router setup

Let's talk about how to setup the routers in here. Ergo, it goes like this routes.init(server); in the server/index.js create function. But why ?

Let's look into the routes/index.js file, the answer lies in there. It is made that way to make the life of the developers easier. It's more informative.

It keeps track of the sequence of the routes, which would be a necessity when the project grows big.

middlewares

The middlewares reside in the server/index.js file, before the routes initiation. Why ? Because, they are called the middlewares, they are supposed to be there by design. There is no use to place them anywhere else, they won't serve their true purpose, i.e. all the requests are supposed to pass through them.

The custom middlewares will be placed in the other parts of the routes based on their requirement, for example, caching middlewares, auth middlewares, or any kind of pre-request processing middlewares and so on.

router.use('/dashboard', authMiddleware, dashboardController);

router.use('/v1', xyzMiddleware, v1ApiController);

Middlewares follow certain specific format. It goes like this...

function xyzMiddleware(req, res, next){
    // stuffs to do
    // add stuffs to request, or change req paramaters, 
    // do whatever you want with those objects, 
    // but once the task is done, call `next()`
}

controller setup

Why is there a controller here ? What is a controller ? What does it do ? Well, let's answer there question here ...

A controller is a piece of code where you start assigning/ defining tasks that is to be done if a request is made to that route, whether GET, PUT, POST or whatever. You will have to define tasks for everything in here, if you want it to act that way.

It is where the true purpose of the request is served. You split the major routes into smaller ones and start writing actions for all the routes, testing them ( most probably using postman or any custom script ) and documenting them.

services setup

What does services do them ? Well, when controller starts assigning/defining tasks, most of the times, there are many common tasks for a lot of routes, this is where services come-up.
We identify the tasks, for example, fetching the active user data from the db, is a very common task. So, we write down the codes for it into a function as a service and just use it when required. This makes maintenance of the server a hell of a lot easier.
Otherwise, every time we need to make some changes, we would have to go all the way to find all such functions and methods and actions to make that specific change and it will make the life of a developer a lot harder.
This whole process is called refactoring. There are courses for these.

That's all for setting up a scalable node architecture. If you have any doubts or issues. Reach out to me at : [e-mail].

!! Happy Coding !!