Creating a REST API With Node.js and Oracle Database

Node.js and REST APIs go hand in hand. In fact, Ryan Dahl (the creator of Node.js) once described the focus of Node.js as "doing networking correctly." But where should you start when building a REST API with Node.js? What components should be used and how should things be organized? These are difficult questions to answer — especially when you're new to the Node.js ecosystem.

You could choose to use low-level packages and lots of custom code to build an API that's highly optimized for a specific workload. Or you could use an all-in-one framework like Sails.js, where many of the decisions have been made for you. There is no right or wrong answer: the best option will depend on the type of project you're working on and where you want to invest your time.

In this series, I'll assume you're new to Node.js and show you how to build a REST API that attempts to balance granular control and magical black boxes. The goal will be to create an API that supports basic CRUD functionality on the EMPLOYEES table in the HR sample schema. By the end of this series, you should be able to make decisions about what's best for your own projects.

This post will provide the links to all the posts in the series, details on the target environment, and an overview of the high-level components that I'll use in the project. The series will include the following parts (links will become active as I publish the content).

1. Web Server Basics
2. Database Basics
3. Handling GET requests
4. Handling PUT, POST, and DELETE requests
5. Adding pagination, sorting, and filtering to GET request

The sample code for each part will be made available in the javascript/rest-api directory of the oracle-db-examples repo on GitHub.

Target Environment

For consistency, the instructions I use throughout the series will assume that you're working with the Oracle Database Developer VM and that Node.js version 8 or higher is installed in the VM. See this post for instructions setting up this type of environment.

I generally prefer to run Node.js in my host OS and communicate with the database in the guest VM. You may adapt the instructions to do this if you want — just be aware that doing so will require additional installation steps to get the driver working on your platform.

High-Level Components

I like to organize my REST APIs into four core components or layers. Incoming HTTP requests will usually touch each of these layers in turn. There may be a lot more going on depending on the features an API supports, but these components are required.

• Web server: The role of the web server is to accept incoming HTTP requests and send responses. There are many options for web servers in Node.js. At the lowest level, you could use the built-in modules, such as http, https, and http2. For most folks, those modules will be too low-level. I like to use Express for the web server as it's very popular, flexible, and easy to use. There are many other options, such as restify, kracken, and hapi. You might consider some of these options as you experiment more with APIs over time.
• Router: Routing logic is used to define the URL endpoints and HTTP methods that the API will support. At runtime, this layer will map incoming requests to the appropriate controller logic. The implementation of the routing logic is almost always tied to the choice web server as most include a means to define routes. I'll use the Router class that comes with Express to create a single router for the app.
• Controllers: The controller layer will be comprised of one JavaScript function for each URL path/HTTP method combination defined in the router. The function will inspect the request and pull data from it (URL, body, and HTTP headers) as needed, interact with appropriate database APIs to fetch or persist data, and then generate the HTTP response.
• Database APIs: The database APIs will handle the interactions with the database. This layer will be isolated from the HTTP request and response. Some developers will prefer to use an Object Relational Mapper (ORM) such as Sequelize to abstract away the database as much as possible. For those folks, this layer is often called the model layer because ORMs work by defining models in the middle tier. I'm going to stay lower level and work directly with the Oracle Database driver for Node.js (node-oracledb).

Click here to get started building a REST API with Node.js.