Node.js Secure REST API Development

Editor’s note: This article was revised on December 2, 2022. The update reflects current editorial standards and incorporates new sources.

Application programming interfaces (APIs) are ubiquitous. They facilitate seamless communication between software components, both internal and external, a crucial factor for scalability and reusability.

Public-facing APIs have become commonplace for online services, allowing developers to integrate features such as social media logins, payment gateways, and analytics effortlessly. The prevalent standard for this is representational state transfer (REST).

Why choose Node.js for building a REST API? While numerous platforms and languages can achieve this – ASP.NET Core, Laravel (PHP), or Bottle (Python) are some examples – JavaScript reigns supreme as the most favored language](https://survey.stackoverflow.co/2022/#most-popular-technologies-language-prof) among developers. Therefore, this tutorial will construct a rudimentary yet secure REST API back end using components familiar to [JavaScript developers:

Node.js, with which the reader should possess some prior knowledge.
Express.js, a framework that streamlines common web server tasks and is a staple in Node.js REST API development.
Mongoose, bridging our back end to a MongoDB database.

This tutorial assumes familiarity with the terminal (or command prompt).

Note: This tutorial won’t delve into front-end development, but the shared JavaScript foundation simplifies code reuse – such as object models – throughout the stack.

Understanding REST API Architecture

REST APIs utilize a standardized set of stateless operations to access and manipulate data. Inherent to the HTTP protocol, these operations underpin fundamental create, read, update, and delete (CRUD) functionalities, albeit not in a strict one-to-one mapping:

POST (creates a new resource or submits data)
GET (retrieves a list of resources or a specific resource)
PUT (creates or fully replaces a resource)
PATCH (partially updates/modifies a resource)
DELETE (removes a resource)

By employing these HTTP operations and a resource name as an address, we can construct a Node.js REST API. This involves creating an endpoint for each operation. Adhering to this pattern provides a stable and intuitive foundation for rapid code evolution and straightforward maintenance. This foundation also simplifies third-party feature integration, most of which rely on REST APIs.

Let’s embark on creating our secure Node.js REST API.

This tutorial focuses on building a common (and highly practical) secure REST API for a resource named users, structured as follows:

id (an automatically generated UUID)
firstName
lastName
email
password
permissionLevel (defines user privileges)

We will implement the following operations for this resource:

POST on /users (creates a new user)
GET on /users (lists all users)
GET on /users/:userId (retrieves a specific user)
PATCH on /users/:userId (updates user data)
DELETE on /users/:userId (deletes a user)

For access tokens, we will utilize JSON web tokens (JWTs), creating an auth resource that receives user credentials (email and password) and returns an authentication token. (Dejan Milosevic’s comprehensive article on JWT for secure REST applications in Java provides further insights; the principles remain consistent.)

Setting Up Our Node.js REST API Tutorial

Start by ensuring you have the latest Node.js version installed. This article uses version 14.9.0; older versions might suffice.

Next, verify the installation of MongoDB. While we won’t delve into the intricacies of Mongoose and MongoDB, initiate the server in interactive mode (from the command line as mongo) instead of as a service. We’ll interact directly with MongoDB at one point, bypassing our Node.js code.

Note: With MongoDB, unlike some RDBMS systems, there’s no need to pre-create a database. Our Node.js code will automatically trigger its creation upon the first insert operation.

Instead of providing a complete project codebase, this tutorial encourages you to clone the companion repo and follow along with the key points. Alternatively, copy specific files and snippets from the repository as needed.

Navigate to the rest-api-tutorial/ folder in your terminal. Observe the three module folders:

common (manages shared services and inter-module information)
users (encompasses everything user-related)
auth (handles JWT generation and the login process)

Execute npm install (or yarn if available).

You’ve successfully set up the dependencies for our simple Node.js REST API back end!

Constructing the User Module

We’ll use Mongoose](https://mongoosejs.com/), an object [data modeling (ODM) library for MongoDB, to define the user model within the user schema.

Begin by creating the Mongoose schema in /users/models/users.model.js:

1
2
3
4
5
6
7
const userSchema = new Schema({
   firstName: String,
   lastName: String,
   email: String,
   password: String,
   permissionLevel: Number
});

With the schema defined, attaching it to the user model is straightforward.

1
const userModel = mongoose.model('Users', userSchema);

This model allows us to implement CRUD operations within our Express.js endpoints.

Let’s start with user creation by defining the Express.js route in users/routes.config.js:

1
2
3
app.post('/users', [
   UsersController.insert
]);

This route is integrated into our Express.js app in the main index.js file. The UsersController object, imported from our controller, handles password hashing (defined in /users/controllers/users.controller.js):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
exports.insert = (req, res) => {
   let salt = crypto.randomBytes(16).toString('base64');
   let hash = crypto.createHmac('sha512',salt)
                                    .update(req.body.password)
                                    .digest("base64");
   req.body.password = salt + "$" + hash;
   req.body.permissionLevel = 1;
   UserModel.createUser(req.body)
       .then((result) => {
           res.status(201).send({id: result._id});
       });
};

We can now test our Mongoose model. Run the Node.js API server (npm start) and send a POST request with JSON data to /users:

1
2
3
4
5
6
{
   "firstName" : "Marcos",
   "lastName" : "Silva",
   "email" : "marcos.henrique@toptal.com",
   "password" : "s3cr3tp4sswo4rd"
}

Various tools are available for this. We’ll cover Insomnia later, but you can utilize Postman, cURL (command-line), or Bruno. Even JavaScript from your browser’s developer console works:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
fetch('http://localhost:3600/users', {
        method: 'POST',
        headers: {
            "Content-type": "application/json"
        },
        body: JSON.stringify({
            "firstName": "Marcos",
            "lastName": "Silva",
            "email": "marcos.henrique@toptal.com",
            "password": "s3cr3tp4sswo4rd"
        })
    })
    .then(function(response) {
        return response.json();
    })
    .then(function(data) {
        console.log('Request succeeded with JSON response', data);
    })
    .catch(function(error) {
        console.log('Request failed', error);
    });

A successful post should return the created user’s ID: { "id": "5b02c5c84817bf28049e58a3" }. Let’s add the createUser method to the model in users/models/users.model.js:

1
2
3
4
exports.createUser = (userData) => {
    const user = new User(userData);
    return user.save();
};

Next, we’ll implement user retrieval via ID using the /users/:userId endpoint.

Start with the Express.js route in /users/routes/config.js:

1
2
3
app.get('/users/:userId', [
    UsersController.getById
]);

Create the controller in /users/controllers/users.controller.js:

1
2
3
4
5
exports.getById = (req, res) => {
   UserModel.findById(req.params.userId).then((result) => {
       res.status(200).send(result);
   });
};

Add the findById method to the model in /users/models/users.model.js:

1
2
3
4
5
6
7
8
exports.findById = (id) => {
    return User.findById(id).then((result) => {
        result = result.toJSON();
        delete result._id;
        delete result.__v;
        return result;
    });
};

The response should resemble:

1
2
3
4
5
6
7
8
{
   "firstName": "Marcos",
   "lastName": "Silva",
   "email": "marcos.henrique@toptal.com",
   "password": "Y+XZEaR7J8xAQCc37nf1rw==$p8b5ykUx6xpC6k8MryDaRmXDxncLumU9mEVabyLdpotO66Qjh0igVOVerdqAh+CUQ4n/E0z48mp8SDTpX2ivuQ==",
   "permissionLevel": 1,
   "id": "5b02c5c84817bf28049e58a3"
}

Note the visible hashed password. While shown for demonstration, it’s crucial never to expose passwords, even hashed ones, in a production environment. Also, observe the permissionLevel, which we’ll leverage for user permissions later.

Following the established pattern, let’s add user update functionality. We’ll utilize PATCH, allowing us to send only the fields requiring modification. The Express.js route will be PATCH to /users/:userid. While we’ll need validation to restrict changes to the user or admins (and only admins can modify permissionLevel), we’ll address this after implementing the auth module. For now, the controller looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
exports.patchById = (req, res) => {
   if (req.body.password){
       let salt = crypto.randomBytes(16).toString('base64');
       let hash = crypto.createHmac('sha512', salt).update(req.body.password).digest("base64");
       req.body.password = salt + "$" + hash;
   }
   UserModel.patchUser(req.params.userId, req.body).then((result) => {
           res.status(204).send({});
   });
};

We’ll use HTTP code 204 (No Content) to signal a successful update without a response body.

Add the patchUser method to the model:

1
2
3
4
5
exports.patchUser = (id, userData) => {
    return User.findOneAndUpdate({
        _id: id
    }, userData);
};

The following controller implements user listing with a GET request to /users/:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
exports.list = (req, res) => {
   let limit = req.query.limit && req.query.limit <= 100 ? parseInt(req.query.limit) : 10;
   let page = 0;
   if (req.query) {
       if (req.query.page) {
           req.query.page = parseInt(req.query.page);
           page = Number.isInteger(req.query.page) ? req.query.page : 0;
       }
   }
   UserModel.list(limit, page).then((result) => {
       res.status(200).send(result);
   })
};

The corresponding model method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
exports.list = (perPage, page) => {
    return new Promise((resolve, reject) => {
        User.find()
            .limit(perPage)
            .skip(perPage * page)
            .exec(function (err, users) {
                if (err) {
                    reject(err);
                } else {
                    resolve(users);
                }
            })
    });
};

The list response will be structured as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
[
   {
       "firstName": "Marco",
       "lastName": "Silva",
       "email": "marcos.henrique@toptal.com",
       "password": "z4tS/DtiH+0Gb4J6QN1K3w==$al6sGxKBKqxRQkDmhnhQpEB6+DQgDRH2qr47BZcqLm4/fphZ7+a9U+HhxsNaSnGB2l05Oem/BLIOkbtOuw1tXA==",
       "permissionLevel": 1,
       "id": "5b02c5c84817bf28049e58a3"
   },
   {
       "firstName": "Paulo",
       "lastName": "Silva",
       "email": "marcos.henrique2@toptal.com",
       "password": "wTsqO1kHuVisfDIcgl5YmQ==$cw7RntNrNBNw3MO2qLbx959xDvvrDu4xjpYfYgYMxRVDcxUUEgulTlNSBJjiDtJ1C85YimkMlYruU59rx2zbCw==",
       "permissionLevel": 1,
       "id": "5b02d038b653603d1ca69729"
   }
]

Finally, let’s implement user deletion with DELETE at /users/:userId.

The deletion controller:

1
2
3
4
5
6
exports.removeById = (req, res) => {
   UserModel.removeById(req.params.userId)
       .then((result)=>{
           res.status(204).send({});
       });
};

Similar to updates, the controller returns HTTP code 204 for confirmation.

The model method for deletion:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
exports.removeById = (userId) => {
    return new Promise((resolve, reject) => {
        User.deleteMany({_id: userId}, (err) => {
            if (err) {
                reject(err);
            } else {
                resolve(err);
            }
        });
    });
};

We’ve implemented the core user resource operations for our Node.js REST API. This code provides a foundation for the REST pattern. We’ll revisit it to add validations and permissions, but first, let’s focus on security by creating the auth module.

Building the Auth Module

Before securing the users module with permissions and validation, we need a mechanism to generate valid user tokens. We’ll generate a JWT upon successful user authentication (email and password). JWTs allow users to make multiple requests without repeated validation. They typically have an expiration time, and refreshing the token periodically enhances security. For simplicity, this tutorial will use a single token per login.

First, create an endpoint for POST requests to /auth:

1
2
3
4
{
   "email" : "marcos.henrique2@toptal.com",
   "password" : "s3cr3tp4sswo4rd2"
}

Before the controller, validate the user in /authorization/middlewares/verify.user.middleware.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
exports.isPasswordAndUserMatch = (req, res, next) => {
   UserModel.findByEmail(req.body.email)
       .then((user)=>{
           if(!user[0]){
               res.status(404).send({});
           }else{
               let passwordFields = user[0].password.split('

Now, in the controller, generate the JWT:

```javascript
exports.login = (req, res) => {
   try {
       let refreshId = req.body.userId + jwtSecret;
       let salt = crypto.randomBytes(16).toString('base64');
       let hash = crypto.createHmac('sha512', salt).update(refreshId).digest("base64");
       req.body.refreshKey = salt;
       let token = jwt.sign(req.body, jwtSecret);
       let b = Buffer.from(hash);
       let refresh_token = b.toString('base64');
       res.status(201).send({accessToken: token, refreshToken: refresh_token});
   } catch (err) {
       res.status(500).send({errors: err});
   }
};

While token refreshing is omitted in this tutorial, the controller is structured to facilitate its implementation later.

Create the Express.js route and invoke the middleware in /authorization/routes.config.js:

1
2
3
4
5
    app.post('/auth', [
        VerifyUserMiddleware.hasAuthValidFields,
        VerifyUserMiddleware.isPasswordAndUserMatch,
        AuthorizationController.login
    ]);

The response will contain the JWT in the accessToken field:

1
2
3
4
{
   "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI1YjAyYzVjODQ4MTdiZjI4MDQ5ZTU4YTMiLCJlbWFpbCI6Im1hcmNvcy5oZW5yaXF1ZUB0b3B0YWwuY29tIiwicGVybWlzc2lvbkxldmVsIjoxLCJwcm92aWRlciI6ImVtYWlsIiwibmFtZSI6Ik1hcmNvIFNpbHZhIiwicmVmcmVzaF9rZXkiOiJiclhZUHFsbUlBcE1PakZIRG1FeENRPT0iLCJpYXQiOjE1MjY5MjMzMDl9.mmNg-i44VQlUEWP3YIAYXVO-74803v1mu-y9QPUQ5VY",
   "refreshToken": "U3BDQXBWS3kyaHNDaGJNanlJTlFkSXhLMmFHMzA2NzRsUy9Sd2J0YVNDTmUva0pIQ0NwbTJqOU5YZHgxeE12NXVlOUhnMzBWMGNyWmdOTUhSaTdyOGc9PQ=="
}

Include this token in the Authorization header of subsequent requests using the format Bearer ACCESS_TOKEN.

Implementing Permissions and Validations Middleware

Let’s define access control for the users resource:

Public access for user creation (registration). JWT is not required here.
Private access for the logged-in user and admins to update the user.
Private access for admins only to delete user accounts.

We need middleware to validate the user’s JWT for all protected routes. This middleware in /common/middlewares/auth.validation.middleware.js can be implemented as:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
exports.validJWTNeeded = (req, res, next) => {
    if (req.headers['authorization']) {
        try {
            let authorization = req.headers['authorization'].split(' ');
            if (authorization[0] !== 'Bearer') {
                return res.status(401).send();
            } else {
                req.jwt = jwt.verify(authorization[1], secret);
                return next();
            }
        } catch (err) {
            return res.status(403).send();
        }
    } else {
        return res.status(401).send();
    }
}; 

We’ll use HTTP error codes for handling request errors:

HTTP 401 (Unauthorized) for an invalid request
HTTP 403 (Forbidden) for a valid request with an invalid token or insufficient permissions

Bitwise AND (bitmasking) helps manage permissions. By representing each permission as a power of 2, each bit in a 32-bit integer acts as a flag. An admin with all permissions would have a value of 2147483647, granting access to all routes. A user with a permission value of 7 would have permissions corresponding to bits 0, 1, and 2 (2^0, 2^1, 2^2).

The middleware for this would look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
exports.minimumPermissionLevelRequired = (required_permission_level) => {
   return (req, res, next) => {
       let user_permission_level = parseInt(req.jwt.permission_level);
       let user_id = req.jwt.user_id;
       if (user_permission_level & required_permission_level) {
           return next();
       } else {
           return res.status(403).send();
       }
   };
};

This generic middleware checks for overlapping bits between the user’s and required permission levels. If a match exists, the result is non-zero, and the action proceeds; otherwise, HTTP 403 is returned.

Add the authentication middleware to the user routes in /users/routes.config.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
app.post('/users', [
   UsersController.insert
]);
app.get('/users', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(PAID),
   UsersController.list
]);
app.get('/users/:userId', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(FREE),
   PermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
   UsersController.getById
]);
app.patch('/users/:userId', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(FREE),
   PermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
   UsersController.patchById
]);
app.delete('/users/:userId', [
   ValidationMiddleware.validJWTNeeded,
   PermissionMiddleware.minimumPermissionLevelRequired(ADMIN),
   UsersController.removeById
]);

Our basic secure Node.js REST API is complete. Now, let’s test it.

Running and Testing with Insomnia

Insomnia is a robust REST client with a capable free tier. While proper error reporting and integrated code tests are ideal, third-party clients are valuable for testing and integration, especially when debugging or error reporting is limited. We’ll simulate application behavior using Insomnia to gain insight into our API.

To create a user, send a POST request with the required data to the /users endpoint. Note the generated ID for later use.

Request with the appropriate data for creating a user

The API should respond with the user ID:

Generate a JWT using the /auth/ endpoint:

The response should be a token:

Confirmation containing the corresponding JSON Web Token

Copy the accessToken, prepend Bearer (with a space), and add it to the request headers under Authorization:

Setting up the headers to transfer contain the authenticating JWT

Without this token, all requests (except registration) would return HTTP 401 due to the permissions middleware. With a valid token, requesting /users/:userId should yield:

Response listing the data for the indicated user

Remember, displaying all fields, including the password, is for demonstration only. Sensitive data should never be exposed in responses.

Now, try listing users:

You’ll encounter a 403 response:

Action refused due to lack of appropriate permission level

The current user lacks sufficient permissions. Modify the user’s permissionLevel from 1 to 7 (or even 5, representing free and paid permissions as 1 and 4, respectively) directly in MongoDB’s interactive prompt:

1
db.users.update({"_id" : ObjectId("5b02c5c84817bf28049e58a3")},{$set:{"permissionLevel":5}})

Generate a new JWT.

With the updated token, the request should succeed:

Test the update functionality by sending a PATCH request with modified fields to /users/:userId:

Request containing partial data to be updated

Expect a 204 response, confirming a successful update. You can verify by requesting the user again:

Finally, let’s delete a user. Create a new user (note the ID) and obtain an admin JWT. Set the new user’s permissions to 2053 (2048 for ADMIN plus 5 from earlier) to enable deletion. Update the Authorization header with the new JWT:

Sending a DELETE request to /users/:userId should result in a 204 response. Verify by listing all users from the /users/ endpoint.

Node.js API Server Tutorial: What’s Next?

You’re now equipped to build simple, secure Node.js REST APIs. Remember to incorporate best practices omitted for brevity:

Implement thorough validations (e.g., ensure unique email addresses).
Include unit tests and robust error reporting.
Prevent users from modifying their own permission levels.
Disallow admins from deleting their own accounts.
Protect sensitive information (e.g., never expose hashed passwords).
Store the JWT secret securely, preferably outside the repository and environment configurations, in a secret distribution mechanism.

As a final exercise, consider converting the Node.js API server codebase from promises to the async/await syntax.

For those interested in taking their JavaScript REST APIs further, we have a TypeScript version of this Node.js API tutorial project available.

); let salt = passwordFields[0]; let hash = crypto.createHmac(‘sha512’, salt) .update(req.body.password) .digest(“base64”); if (hash === passwordFields[1]) { req.body = { userId: user[0]._id, email: user[0].email, permissionLevel: user[0].permissionLevel, provider: ’email’, name: user[0].firstName + ’ ’ + user[0].lastName, }; return next(); } else { return res.status(400).send({errors: [‘Invalid email or password’]}); } } }); };

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

Now, in the controller, generate the JWT:

```javascript
exports.login = (req, res) => {
   try {
       let refreshId = req.body.userId + jwtSecret;
       let salt = crypto.randomBytes(16).toString('base64');
       let hash = crypto.createHmac('sha512', salt).update(refreshId).digest("base64");
       req.body.refreshKey = salt;
       let token = jwt.sign(req.body, jwtSecret);
       let b = Buffer.from(hash);
       let refresh_token = b.toString('base64');
       res.status(201).send({accessToken: token, refreshToken: refresh_token});
   } catch (err) {
       res.status(500).send({errors: err});
   }
};