Without a doubt, Application Programming Interfaces or APIs play a very important role in communication and data exchange between servers and services. From computers to smartphones and Internet of Things (IoT), applications talk and exchange info via APIs. Almost every day we use or interact with an API service, and many sites use a custom API to scale up their website. As such, learning how to develop a custom API adds lots of value to your developer profile.

Motivated by the importance of APIs and the popularity of JavaScript (JS), we’d like to show you how to develop a custom RESTful API using Node.JS and MongoDB. Along the way, you will be able to leverage and improve your JS skills. Developers can also expand this tutorial by using MySQL instead of MongoDB or securing API by adding authentication call-backs.

Tutorial Overview

In this tutorial, we walk you through seven steps for developing a RESTFul API using popular JavaScript frameworks such as Node.JS and Express.JS. In doing so, we learn how to integrate our API with the MongoDB database. Here are the main steps:

1. Project Initialization
2. Install Application Dependencies
3. Run the Application
4. Test the Application
5. Establish Connection with MongoDB
6. Build REST API Endpoints
7. Put Things Together

Some background on REST APIs is helpful for understanding and following this tutorial.

RESTful API Overview

REST stands for REpresentational State Transfer. When a RESTful API is called, the server will transfer to the client a representation of the state of the requested resource. For example, when a developer calls OpenWeather API to fetch weather for a specific city (the resource), the API will return the state of that city, including the temperature, humidity, wind speed, current forecast, extended forecast, and more. The representation of the state can be in a JSON format, and for most web APIs, this is indeed the case. Other possible data formats include XML or HTML. What does the server does when you call it depends on two things that you need to provide to the server:
1. An identifier for the resource. – This is the URL for the resource, also known as the endpoint. In fact, URL stands for Uniform Resource Locator.
2. The operation you want the server to perform on that resource, in the form of an HTTP method. The common HTTP methods are GET, POST, PUT, and DELETE.

Prerequisites:

1. Install Node.js by following the appropriate guidelines for your local machine given here.
2. You may use Node Version Manager to install multiple versions of Node.js on your local machine.
3. Signup for MongoDB Atlas which is a cloud database as a service. We’re using MongoDB Atlas which offers us a free sandbox environment so that we can focus on building our REST API.
4. Code Editor like Visual Studio Code or Sublime Text

1. Project Initialization

We need to create an application folder where our application will reside. To initialize the application, we need to create a package.json file, which will hold all the metadata for the node application. The file allows npm to handle installing the package dependencies and scripts we write to handle the application.
Assuming that you’ve Node.js installed, we can initialize the application from the command line by executing the following:

npm init -y

The above command will create a package.json file.

2. Install Application Dependencies

We need a file that can act as command central for our application. This file will be executed first by npm when we ask it to run our application. This file can have object instances of multiple modules that we write as well as third party modules that we install from the npm directory.
These modules are dependencies of the project. We’ll install a few of these dependencies now:

touch app.js
npm install express mongodb body-parser --save

Using the above commands we created a file called app.js which will be the main entry point to the application, and we installed a few dependencies that are essential to start our application.
These dependencies are:
1. Express: This is a Node.js framework.
2. MongoDB: This is an official module provided by the MongoDB team to help our Node.js application communicate with MongoDB.
3. body-parser: This package will allow us to handle request bodies with Express.

Why use body-parser?

Let’s say you are sending an HTML form data to Node.js server i.e. you made a request to the server. HTTP sends your form data in bits and pieces which are intended to get assembled as they reach their destination. To extract these bits and pieces of data and assemble it so it is in a format that can be useful, we use a body-parser middleware.

3. Run the Application

Let’s run the code for our application –

const Express = require("express");
const BodyParser = require("body-parser");
const MongoClient = require("mongodb").MongoClient;
const ObjectId = require("mongodb").ObjectID;
var app = Express();
app.use(BodyParser.json());
app.use(BodyParser.urlencoded({ extended: true }));
app.listen(5000, () => {});

Here, we’re importing our downloaded dependencies. We initialize the express framework by utilizing the Express object that will use the express framework to start the server and run our application at a given port and configure the body-parser, which is a middleware to parse incoming chunks of data.

4. Test the Application

We can test the application by running the following:

node app.js

The server will be listening on port 5000 for requests according to the above boilerplate we wrote.

5. Establish Connection with MongoDB

We will need the connection string for MongoDB. This can be found in the Atlas dashboard by choosing Clusters, then the Overview tab followed by the Connect button.
We need to add the string to our app.js and make the following changes to the code.

const Express = require("express");
const BodyParser = require("body-parser");
const MongoClient = require("mongodb").MongoClient;
const ObjectId = require("mongodb").ObjectID;
const CONNECTION_URL = ;
const DATABASE_NAME = "accounting_department";


var app = Express();
app.use(BodyParser.json());
app.use(BodyParser.urlencoded({ extended: true }));
var database, collection;

app.listen(5000, () => {
    MongoClient.connect(CONNECTION_URL, { useNewUrlParser: true }, (error, client) => {
        if(error) {
            throw error;
        }
        database = client.db(DATABASE_NAME);
        collection = database.collection("personnel");
        console.log("Connected to `" + DATABASE_NAME + "`!");
    });
});

Here, we’ve defined the connection string to use. You need to add a CONNECTION_URL property according to the connection string you received from MongoDB Atlas. We’ve also defined the database name which we wish to create (if not already present and collection).
We establish a connection once we start again the application and use globally defined variables so that they can be used in each of our endpoints.

Now let’s start designing our HTTP consumable API endpoints.

6. Build REST API Endpoints

Now we’re going to develop endpoints for creating and querying the data. Let’s create an endpoint to add the data. Add the following code to app.js:

app.post("/personnel", (request, response) => {
    collection.insert(request.body, (error, result) => {
        if(error) {
            return response.status(500).send(error);
        }
        response.send(result.result);
    });
});

We aren’t doing any data validation, but when a client makes a POST request to the /personnel endpoint, we take the body and insert it into our collection. Depending on the success or error response of the database, we return information back to the client.

7. Put Things Together

Now, things are starting to come together. Let’s test out our application.

curl -X POST \
    -H 'content-type:application/json' \
    -d '{"firstname":"John","lastname":"Doe"}' \
    https://localhost:5000/personnel

If you do not receive any errors, you’ll see the personnel record for John Doe added into MongoDB database of accounting_department and under collection personnel. Feel free to add more records to your database.

GET

Now let’s create an endpoint to retrieve all the records data. Add the following code to app.js:

 app.get("/personnel", (request, response) => {
    collection.find({}).toArray((error, result) => {
        if(error) {
            return response.status(500).send(error);
        }
        response.send(result);
    });
});

The goal here is to return all data in our collection representing people. We have no query conditions, hence the empty {} in the find command, and the results get converted into an array.
Let’s test this out using cURL, a command-line tool for transferring data and supports HTTP; a very good ad-hoc tool for testing REST services.

curl -X GET https://localhost:5000/personnel

GET (by ID)

By now let’s assume you’ve added more records into your database. API consumers will need to retrieve a single record according to its ID.

Write the following endpoint to your app.js:

app.get("/personnel/:id", (request, response) => {
    collection.findOne({ "_id": new ObjectId(request.params.id) }, (error, result) => {
        if(error) {
            return response.status(500).send(error);
        }
        response.send(result);
    });
});

We’re going to use a route parameter to get specific personnel information from MongoDB. Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response. This time around we have a route parameter called id which will represent an object id in MongoDB. Using the findOne method, we can get a single record based on the criteria included in the object. The id isn’t a string which is why we have to use the ObjectId.

Depending on the actual data in our database, we can do a cURL command similar to this:

curl -X GET https://localhost:5000/personnel/4b103f89403f841059524fd1

Conclusion

In this tutorial, we’ve learned how to develop a custom API and connect it with MongoDB to fetch and manipulate the data. From here, you can take different steps. For instance, you can expand this project by adding more features like data validation to it. You can also improve the API security and salability by following Node.JS best practices. Lastly, you can try this tutorial with MySQL database or another server-side coding language like PHP or Django.
What do you think of this tutorial? What tools are you using to develop REST APIs?