Build a REST API with Node.js and HarperDB
In this post, let’s build a simple REST API using Node.js and HarperDB Cloud. We are also going to use Express as the framework to build the Node.js server.
Join the DZone community and get the full member experience.Join For Free
If you are building an application using Node.js, it can get a little overwhelming since there are a variety of databases to choose from and different ways to build APIs. One way to reduce development time and focus on the problem you are trying to solve is to use a Database as a service to store the data. The advantage of this approach is to use a cloud database system without purchasing hardware which can be cost and time-effective.
- Single endpoint API.
- Allow JSON, CSVs file insertions.
- Support SQL queries for full CRUD operations.
- Supports Math.js and GeoJSON.
- Limited database configuration required.
In this post, let’s build a simple REST API using Node.js and HarperDB Cloud to store some data. We are also going to use Express as the framework to build the Node.js server. It is a minimal and quite unopinionated framework.
Before you begin this tutorial, you’re going to need the following:
- Node.js version above
12.x.xinstalled on your local machine.
- Access to a package manager such as npm or yarn.
- Access to a REST API client such as Postman or Insomnia.
- Access to a HarperDB Cloud instance (free tier).
To continue with the rest of the tutorial, please make sure you have an account with HarperDB Cloud and are logged in.
Start by creating the project directory in a local development environment. Give this directory a name and navigate into it. Then, initialize this project to manage npm dependencies by creating a
--yes flag uses the default settings when initializing a
package.json from the npm config you might have set up.
After the initializing step, let us add an express package. From the terminal window, run the command:
Next, create a new file called
index.js at the root of the project with the following code to trigger a minimal server:
In the above code snippet, the
app is an object provided by Express API for the developer to communicate with the application and bootstrap a server.
Go back to the terminal and trigger the common
node index.js to start the server. This
node command is the simplest way to trigger a development server when building APIs with Node.js. Now, open up your favorite REST client to test APIs. For the demonstration purpose, I am going to use Insomnia.
You can test the API endpoint by invoking a call to
http://localhost:8000 and it is going to return the result as shown below.
Watching File Changes With nodemon
An essential development-related utility library that saves time when working on Node.js projects is nodemon. It’s a tool that helps the development of Node.js based applications by automatically restarting the Node application when file changes in the directory are detected.
To start using it in the current Express server, install it by using
yarn add -D nodemon where
-D flag is used to indicate that the dependency to install is a
devDependency. After installing this dev dependency, open
package.json file and add a start script as shown below.
Now, you can use either
npm run start or
yarn run start command to trigger the server. That's it to set up a basic Node.js server using the Express framework.
Setting up an Instance of HarperDB Cloud
In the introductory section of this post, you get the idea of what HarperDB Cloud is and the features it supports. In this section, let's create the first database instance to store the data for the REST API using this cloud database service.
Assuming by now you have access main dashboard screen as shown below. To create a new instance, click on the plus button.
Then select the HarperDB Cloud Instance option.
One of the main advantages of HarperDB is in querying the data from a database instance. It allows us to query the data either in the form of SQL queries or NoSQL queries. The advantage here is that the power of complex SQL queries can easily be used here to perform an operation. I am going to define all the queries in NoSQL form, however, do not forget to check official docs for more information on performing SQL queries here.
The first query is going to be called
addBook. This query is going to insert the data incoming from an HTTP request.
Each of the query functions as in the above code snippet is going to have at least two parameters:
request: useful when creating or updating a new task and read data from the body (this where BodyParser works like a charm).
response: useful to fulfill that incoming request with a response from the server. Generally, it contains the correct status code of the HTTP status code. This HTTP status code determines whether the incoming request was fulfilled or if there is an error. This the part of the REST paradigm and is considered a best practice.
When inserting data using a NoSQL query, it is mandatory to specify the name of the table in the database. In the current case its
books. Since you have already specified the Schema when creating a connection using the HarperDB client, there is no need to explicitly define it here.
records in HarperDB are similar to rows of data with having each field as a column.
You may have noticed in the above query that I am not explicitly adding an
id attribute to uniquely identify each data record. HarperDB automatically creates a unique
id for each data record.
The data being inserted here has two fields. The
title and the
author for each book. They represent the name of the columns or attributes in each data record. The value of each of these fields is going to be the incoming value from an HTTP request, parsed by the
body-parser middleware function.
Running the First Query to Insert Data
To insert the first data record in the database let's create a route. Open
index.js file in the root directory and import the
routesController. A controller is a naming convention in an Express framework app. It is the business logic that binds the endpoints/routes that are going to define below to what action or operation they will perform on an incoming request on that particular route.
Go back to the REST client and make sure the Node.js server is running from the terminal window.
Add the endpoint which is
http://localhost:8000/books, select the type of the request which is
POST. Select option
Form URL encoded and the two key-value pairs as shown below:
Send button it an HTTP request to insert the data to the HarperDB is made. If it's successful, a success message shown below is returned.
Go back to the HarperDB studio and you are going to see the same data record being shown.
Do notice the two timestamp fields. They are auto inserted by the HarperDB and are auto-maintained.
__createdtime__: to record the timestamp when data is inserted.
__updatedtime__: to record the timestamp when any data field is updated for the last time.
Try to add more values to the database.
Query to Search by Value
HarperDB allows to search database records in a table by using a column field name which is also known as an
attribute. Let's add another query to get a data record when an HTTP request is sent just by searching the name of the author. Open
api/index.js file and the following:
The data returned from the database is going to be in JSON format. Go back to the main
index.js file and add another route.
Open the REST Client and make a request as shown below. The response of this HTTP request is going to be every data record that contains the value of the attribute
Query to Search by Hash
Another important way to search for data in a table is by the unique identifier. HarperDB has a special method to do the same. This method is called
searchByHash and only allows us to search the database table using the identifier specified as has an attribute. In the
api/index.js file, add another query called
When this query successfully runs, the result from the database is only going to show the
title attribute of the data record. This is done by passing the name of an attribute as the value of the
attributes property in the above snippet.
Add the endpoint in the main
Go to the REST client and run the query.
Published at DZone with permission of Aman Mittal. See the original article here.
Opinions expressed by DZone contributors are their own.