Up and Running with Node.js API in 30 minutes

Here’s a small insight on my journey to understanding what API’s are enroute creating an API with authentication. In the course of this journey we’ll build a simple API using NodeJS.

Introduction

- On this exciting journey into the world of Node.js and backend development for web application service (API); I think it would be best to paint a picture of what we hope to achieve at the end of the day.

- By the end, we should be familiar with basics of Node.js and what it can do, build access point to a resource for a book rating app. We’ll be answering questions like

• What is node js?
• How do I run node JS?
• What exactly is an API and how it works?
• What is meant by REST API?

In this article I’ll try to demystify some buzz words around Node.js, MongoDB and REST API development like: Node.js 😁 JavaScript Modules, npm, require, resource as regards API’s. In practice we would also take a look at asynchronous programming dwelling on callbacks and promises.

• At the end of this hands-on article, we would build a simple Node.js API for a book-rating application
• What do we need for this? The first question that comes to mind, what do we need under our belt to build a Node.js API? Firstly, a basic programming knowledge, basic understanding of JavaScript: variables, functions, loops, conditional statements, callbacks and promises.

Let’s dive right in.

What exactly is an API?

API is an acronym for Application Programming Interface; simply put it is a channel to access information between an enterprise and applications that uses its assets/resources.

These resources reside on a host database system. We will be looking at MongoDB, a NoSQL database system.

In this article, we will be looking at Web API’s. These are API’s used in the context of web development. Here it provides a well-documented structure of data flow either to or from the server.

APIs basically abstract the underlying implementation of information generation but only expose the data the developer needs. Enough said, I think the best way to learn about APIs is by creating one.

To achieve this, we would be using a server-side JavaScript technology: Node.js which makes it super simple to create APIs just by calling a send() on the response object with the parameters passed in as an object. This takes us to the next question.

What is Node.js?

Node.js came about when the developers took JavaScript that usually only ran on the browser to the server, granting them access to the low level APIs. This meant that we could create applications using JavaScript outside the context of the browser.

With Node.js we could do much more than the basic functionalities that the browser environment affords, giving us leverage to do much more like other programming languages. We would be able to do things like manipulate the file system, querying databases, creating command line applications and obviously creating web servers. Smiles… Feeling macho right?

Let’s take a deeper look at the formal definition of Node.js from the Node.js website:

“Node.js is a JavaScript runtime built on Chrome’s V8 engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient.”

• V8 engine is an open source JS engine written in C++ that takes JS code and compiles to machine language, this is what makes node blazing fast as computers only understand bits.
• I/O: input/output communications from node into the Internet of Things (database, file change, http requests…).
• Non-blocking: while one process is making a request (I/O) other processes can also be making requests. This is a core feature of Node.js and it makes applications run much faster as multiple requests can be going on at the same time.

It is worth stating that Node.js uses a single thread. All these features put together makes Node.js lightweight and efficient.

Another thing that has made Node.js so popular is the node ecosystem, its community of developers. Npm (package manager for javascript) is the largest ecosystem of open source libraries in the world. People develop new libraries that solve common problems, so you can focus on the specifics of your program. Node.js programmers take advantages of the vast community of developers.

How do I run Node JS?

Running Node.js is very simple. You basically have to run just a simple command on the CLI (command line interface).

node file-name

How do I install Node.js?

Before we go ahead, lets install Node.js. Head to the website www.nodejs.org and download the recommended installation file with long time support.

It’s just a simple file that you can run, click next a few times and BOOM… you’re done.

Install MongoDB

Software required for this hands-on API development with Node.js is MongoDB, an open source document database (NoSQL).

To download this free software, head over to https://www.mongodb.com, click on the Get MongoDB button on the top right corner of the page.

This would lead you to a download page. Click on the “Server” tab to download the MongoDB Server. For a quick Windows installer select the MSI option of the Package dropdown menu then click on the big green button to download the installer.

Go with the default installation options and you’ll be fine.

The installed MongoDB does not have a database viewer like the phpmyadmin that comes with the popular LAMP stack. So we would need a database visualizer to monitor our persisted data.

There are lots of MongoDB GUIs out there, so use anyone that works well for you. But we would go with Robo 3T (free lightweight GUI for MongoDB). It’s available at https://robomongo.org/. Just download and install with the default settings.

Postman is another piece of software that would be required for this project. It is used to test API endpoints. It’s free and also has a chrome extension. But I’ll be downloading and installing the desktop version at https://www.getpostman.com/

To setup the MongoDB server, create a MongoDB preferably the root of the harddisk. Inside that directory create a “data” directory where the database files would be stored.

Next start up the mongodb server with these commands from your cmd. NOTE: The x.x is a folder inside server folder indicating the version of you mongodb installed. This is basically navigating to the bin directory of the mongodb installed.

cd /

cd Program Files/mongodb/server/x.x/bin

NOTE: The x.x is a folder inside server folder indicating the version of you mongodb installed. Next run the following commands from the cli to start the mongodb server.

mongod --dbpath= /mongodb/data

Set-up the MongoDB server and get it running with the following commands from the cli.

When you see a report “…waiting for connections on port 27017” means your MongoDB server is up and running.

Yaah!!! We are good to start creating and running our Node.js application.

Section Two

To get started, we’re going to create a folder for our application: book-api. You could use the OS GUI to do that or the CLI.

To use the cli , open the cmd application; navigate to the directory you want the application to reside. Run the following commands:

mkdir book-api

cd book-api

Next run npm init to initialize the node application, this creates a package.json file that has all the some basic settings the app requires.

npm init

Next we install some node dependencies we’ll be using. Dependencies are just JavaScript codes written by other developers to make your development easy. Remember we talked about the node ecosystem that drives the popularity of Node.js.

We will be installing the following packages to our application: mongoose, express, body-parser and lodash by running the following command on the cli. (*** internet connection is needed to download these packages to our application).

npm install mongoose express body-parser lodash --save

You will notice that on completion of the command execution, the book-api directory now contains a “node_modules” directory. This folder holds all the files that the installed modules require to function. They should not be tempered with because your application depends on them to function properly. Create a server folder in the book-api to hold all the resources the server needs to function.

Create two directories in the server directory: “db” and “models”.

Open the application in your preferred code editor. I’ll be using Visual Studio Code.

Next we have to setup a connection to the MongoDB database, specifying the url and the project database name.

To do so, create a mongoose.js file in the db folder created. Next enter these lines of code to setup our database connection.

The final part of the database setup before creating the book-api endpoints is to setup the database schema using mongoose.

So we have to create a mongoose schema and model for the book collection. This gives a structure of how our book document would look like. It contains an object of database fields and their properties. Very easy to follow, for more information head to the Mongoose Docs.Create a book.js file in the “models” directory. Enter the following code.

Enter the following code.

Our web API would be served from a server.js file in the server folder created. So go ahead and create a server.js file inside of server directory.

Next set up the web-server with express.

Open the server.js file created in your favourite code editor; enter the following lines of codes.

Lines 1–3 are used to load the 3rd party modules installed (express, body-parser and lodash). On line 5 we import the destructured Book mongoose model from the ‘./models/book’. Notice the period in front of the directory path, it indicates that the module is actually a user defined module.

Next on line 7 we set the server’s port; which could be gotten from the environment variables if it exists or statically (3000).

Lin 9 creates the express web server called app.

Line 10 sets an express middleware.

A middleware is used to filter requests sent to the server. It’s handles requests from client, processes them before it sends the request to the server. You could look at it like some sort of PG (parental guidance) viewing movies (requests) before allowing dependants view them (response). If by the parent’s (middleware) discretion the movie is X-rated then the kids do not get to watch else they can watch it.

Body-parser helps to parse the request body into a JavaScript object that can be accessed in the req.body object.

Finally, creating the express application does not make the app available, to do so we call listen() on the app. It receives the port and an optional callback function that gets executed when the app is live. (line 13–15)

To test this web server, run the following code from the CLI: (node server/server)

Note: you have to do this from the root of your node application (book-api) as seen above.

Once the server is up and running it would log a statement on the CLI: ‘Server running on port 3000’.

Shut down the server by pressing Ctrl+C on a windows system or Cmd+C.

We’ll be creating these CRUD endpoints.

i. POST /books

ii. GET /books

iii. GET /book/id

iv. PATCH /book/id

v. DELETE /book/id

POST /books

This endpoint would be called to save a book into our database. It would receive the json object with fields: title, author, publisher and year. Insert this block of code before the app.listen() statement.

On line 12 we call the post() on the app. This creates a POST endpoint with the path as the first parameter passed into the function. It also requires a callback function that takes in the request object and the response object in that order.

For simplicity, we’ll be using arrow functions.

On line 13 we pull out all the parameters we’ll be needing from the request body (set by the body-parser middleware) using lodash pick(). Lodash pick() requires two paramters: the object to pick from and an array of the object properties to pull out, returning the new object.

Next we create a new mongoose Book object by call the Book constructor imported on line 5 passing in the object (sent from the post request) needed to initialize the mongoose Book object.

Lines 15–17 uses the promisify version of the mongoose save library. We first call the save() on the mongoose object created on line 14. The “then()” runs when successful returning the object on success. This object is sent back as a response with a 200 status, notifying the user that the request was successful.

NOTE: All the methods we’ll be calling on the mongoose objects are defined in the mongoose documentation. But are very easy to follow as their names speak volume already.

Next start the server as before. (node server/server)

To test our API, we’ll be using the Postman application. It’s an app used to test APIs.

Open Postman,

i. Change the http request verb from the default ‘GET’ to ‘POST’

ii. Enter the url “localhost:3000/api/books

iii. Select the body tab just beneath the entered url

iv. Select the “raw” option

v. Change the text dropdown option to JSON (application/json)

vi. Enter the JSON data of the request we want to make:

vii. Click send to initiate the request

It should come back with a response with status code 200 or otherwise if there was an error.

If you encountered an error, check through comparing yours code with the ones above or check the link to the github repo for the finished app.

When you view the database with the database viewer (Robo 3T) you’ll see some extra fields like _id, it’s a unique field auto generated by the mongodb database.

Create other entries too as you please.

GET /books

The GET /books endpoint would be used to retrieve all the books in the database. It would return an array of object (books).

Use Postman like before to test this endpoint. url: localhost:3000/api/books.

GET /book/id

This API endpoint would be used to fetch data from the database that has the _id passed into the route.

Use Postman to test this endpoint.(xxxxxxxxxxx _id field from a mongoose document and set the http verb to GET) url: localhost:3000/api/book/xxxxxxxxxxxxxxxx

Notice the :id on line 28, it’s a placeholder for a variable that would be passed in from the url. Line 29 saves the variable passed in available in the req.params object with the same attribute name as the placeholder on line 28.

Line 28 checks if a book with the id was found and returns a response with the book or a 404 error status.

Next PATCH /book/id

This endpoint helps to update/modify an existing record with the “id” that was passed in.

Use Postman to test this endpoint.(xxxxxxxxxxx _id field from a mongoose document, don’t forget to set the body of the request and set the http verb to PATCH) url: localhost:3000/api/books/xxxxxxxxxxxxxxxx

In the mongoose findByIdAndUpdate () we pass in a few parameters,

• the id of the document to be updated.
• an object with mongoose update operator: $set with its value set to an object with properties that need to be updated.
• The third parameter: new: true, tells mongoose to return the updated object.

DELETE /book/id

This endpoint would be responsible for deleting an existing document in the book collection that matches the id passed in.

Use Postman to test this endpoint.(xxxxxxxxxxx _id field from a mongoose document and set the http verb to DELETE) url: localhost:3000/api/books/xxxxxxxxxxxxxxxx

Whew!!! Guess this must have been an exciting ride with ease of creating API’s with Node.js, Express and MongoDB. The next part of this publication would treat API’s that need authentication. In that part we would create user’s who can rate books only if authenticated. Fee free to share your thoughts on the article.

Finally, click here to clone the repo on the project.