Creating a REST API with Node.js and Oracle Database

By March 23, 2018 Uncategorized

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 or ORDS, 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 an informed decision 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 sample code for each post 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 start at a 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.


  • João Loureiro says:

    OH MY GOD!


    All 5 parts of it! Congratulations e thank you very much!

  • paddy says:

    Love your article, you made my life easier. Thank you

  • Nice article..keep sharing…

  • Toddy says:

    A M A Z I N G !

  • mfp says:

    Truly amazing article. This is the best thing I have read since Gibbons “Rise and Fall of the Roman Empire”

  • Rafae says:

    You’re a lifesaver man.

  • Abhijit R says:

    Best article for kick starting REST + Node + Oracle. I had been searching for this for long.

  • Laerte Fernandes says:

    Excellent post. Really usefull starting to the node, well explained and complete. Thank you so much.

  • bayu says:

    Excellent post, hope you write even more articles related with this topic..thank you Dan

  • Michael says:

    Dear Mr. danmcghan.
    I just can’t thank you enough. Great article by you, it helps me a lot!

    For those who work with pre-12c Oracle DB – there are no OFFSET and FETCH parameters in Select.
    This is how I solved it for

    –//// Queries for GET //////
    — 20 skip, No limit
    SELECT *
    FROM (SELECT a.*, rownum rnum
    ORDER BY DEPID ) a )
    WHERE rnum > 20;

    — No skip, 5 limit
    SELECT *
    FROM (SELECT a.*, rownum rnum
    WHERE rownum <= 5);

    — 20 skip, 5 limit
    SELECT *
    FROM (SELECT a.*, rownum rnum
    WHERE rownum 20;