Creating a REST API: Web Server Basics

By March 23, 2018 Uncategorized

The web server is one of the most important components of a REST API. In this post, you will start your REST API project by creating some initial directories and files. Then you’ll create a web server module and wire things up so that the web server starts up and shuts down correctly. Finally, you will add some basic logging capabilities to the web server.

Starting up and saying hello

The code in this project will be organized using a generic directory structure that can be adjusted and built out over time as needed. In the VM, open a new terminal by going to Applications > Favorites > Terminal, then run the following commands.

The project will be contained in the hr_app directory. The directories within hr_app should be easy to understand based on their names and the “High-level components” overview in the parent post. The index.js file can be thought of as the “main” file in a Java app – it will be the entry point of the application. We will be adding code to that file and the web-server.js files in the config and services directories in this post.

Go to Applications > Favorites > Files to open the file browser and navigate to Home > hr_app > config. Double-click web-server.js to open it in the gedit text editor. Copy and paste the following code into the file, then save your changes.

This is a simple JavaScript module that exposes a single property named port. In Node.js, the process object has an env property that contains the user environment. I’m using that to set the value of port to the value of the environment variable HTTP_PORT. If that environment variable isn’t defined, the default value will be 3000. It’s common to derive ports from environment variables as they may vary in different environments or be randomly assigned at runtime.

With the configuration file ready, you can turn your attention to the web server module. Open the services/web-server.js file in gedit. Copy and paste the following code into the file and save your changes.

Here’s a breakdown of the web server module so far:

  • Lines 1-3: Several modules are required in. The http module is included with Node.js but the express module will need to be installed via npm.
  • Lines 7-27: A function named initialize is declared. The function immediately returns a promise which is resolved or rejected depending on whether the web server is started successfully.
    • Lines 9-10: A new express application is created (which is really just a function) and then used to create an http server via the http module.
    • Lines 12-14: The app’s get method is used to add a handler for GET requests that come in on the root (/) path. The callback function (also called a middleware function) will be invoked when such a request is received and it will use the “response” parameter (res) to send a “Hello World!” response to the client.
    • Lines 16-24: The server’s listen method is used to bind to the specified port and start listening for incoming requests.
  • Line 28: The initialize function is exported from the module so it can be invoked externally.

With the web server module defined, you can put it to use in the main module. Open index.js, copy and paste the following code into it, and save your changes.

The main module brings in the web server module, and then it defines and invokes an async function named startup. Because the web server module’s initialize function returns a promise, you can use it with async/await and wrap it in a try-catch block (click here to learn more about async/await). If the initialize function finishes successfully, then the web server will be running; otherwise, any exceptions will be caught and handled.

All you need to do now is initialize npm and install express – then you can run the app. Run the following commands in the terminal from the hr_app directory.

The npm init command is used to create the package.json file, which npm uses as a manifest file (the -y flag accepts the default options). The npm install command is used to install express (the -s flag adds express to the list of dependencies in the package.json). Npm stores the modules you install in the node_modules directory. It also creates a file named package.lock.json to ensure identical module trees across a team of developers.

Do you see a message telling you the web server is listening on localhost:3000? Congratulations, you created an express based web server! Open Firefox and navigate to http://localhost:3000.

And there it is, yet another “Hello World”. While not particularly exciting, it’s an important first step for your API. When you’re ready you can shut down the server by returning to the terminal and pressing ctrl+c.

Controlling the shutdown

While shutting down by pressing ctrl+c works, you didn’t have much control over how it happened. To control the shutdown process, you will need to explicitly close the web server and exit the Node.js process.

Append the following code to the bottom of the web server module.

The close function returns a promise that is resolved when the web server is successfully closed. The httpServer.close method stops new connections from being established, but it will not force already opened connections closed. Depending on how many connections are open and what they are doing, you might have to wait a bit for the callback to fire. Though you will not do it in this module, it is possible to use custom code or npm modules, such as http-shutdown, to force open connections closed.

With the close function in place, the main module can be updated to invoke it at the right times. Append the following code to the end of index.js.

SIGINT and SIGTERM events are related to signals that can be sent to the process to shut it down, such as when ctrl+c is pressed. The uncaughtException event will occur when a JavaScript error is thrown but not caught and handled with a try-catch statement.

Try running and shutting down the application again. You’ll know everything is working correctly when you see the “shutting down” messages in the terminal.

Adding web server logging

There’s just one last thing to round out our web server module: HTTP logging. There are various modules you could use for this type of logging, but morgan is known to be one of the best (and simplest). Let’s install morgan with npm.

Next, add the following line to services/web-server.js under the line that requires express (line 2).

Now you can incorporate morgan as a middleware function that all requests will go through with app.use. Add this line before the app.get call that produces the “hello world” message.

Note that app.use is creating a pipeline of middleware functions that can interact with HTTP requests and responses. The middleware will execute in the order that they are included.

Restart the app and position the terminal so you can see it and Firefox at the same time. Each time you reload the page in Firefox you should see a new log entry appear in the terminal. By default, morgan streams log info to STDOUT (which is displayed in the terminal).

This is as far as I’ll go with logging in this series. However, in a production application, you might want to stream morgan’s output to an HTTP access log file. You might also consider a logging utility, such as Winston, for debugging and tracing as an alternative to the console object.

The next post in this series focuses on database basics–including connection pooling–that will help you understand and build REST APIs for Node.js.


  • Saran says:

    Another impressive and useful Blog. Thanks!

  • Jan says:

    Great read, thanks.

  • Sebastian says:

    Excellent article! I get the following error when executing the third statement (node.). What can be?
    async function startup () {
    SyntaxError: Unexpected token function
    at Object.exports.runInThisContext (vm.js: 76: 16)
    at Module._compile (module.js: 542: 28)
    at Object.Module._extensions..js (module.js: 579: 10)
    at Module.load (module.js: 487: 32)
    at tryModuleLoad (module.js: 446: 12)
    at Function.Module._load (module.js: 438: 3)
    at Module.runMain (module.js: 604: 10)
    at run (bootstrap_node.js: 394: 7)
    at startup (bootstrap_node.js: 149: 9)
    at bootstrap_node.js: 509: 3

  • Sebi says:

    Beautiful! This is just what I needed.
    Thank you.

  • Mike Lee says:

    This is fantastic! Can’t wait for the next series where you filter, sort and paginate the results. Wonderful work!

    • danmcghan says:

      You don’t have to wait… I just published the last part about 2 hours ago! 🙂

      Though that’s the last “core” post in the series, there will be more follow-up posts…

  • donny says:

    Easy to follow and to practice since i am a newbie

  • mercaal says:

    Very helpful. Kodus to you Dan. This is why the community thrives because of someone like you.

  • Irfan says:

    Your explanation has huge clarity. I haven’t seen people explaining it with this much clarity on internet.

  • Alvondi says:

    Great article, Congrats!

  • Halil says:

    Finally!!! No more words, thanks for brief and clear information on this topic !

  • Quan says:

    Hi all,

    Do we need to install the VM to learn Nodejs and OracleDB?
    What happend if I do not íntsall the VM?


    • danmcghan says:

      Hi Quan,

      Thanks for your question! No, you don’t need to use the VM, but the instructions are based on the VM. So, if you use another database, you’ll need to make minor adjustments for the database environment you plan to use.

  • Ahmed says:

    This is super awesome presentation and clarity

  • Benjamin says:

    This tutorial is just awesome, thank you very much! It helps me to get the communication done between VueJS Client Application and my Oracle SQL Database Server… so, you just told me that there is something additional necessary to get this done. 😀 Thanks!