Node.js API Tutorial Part 1

Node.js is a great technology for creating web apps!
In this first tutorial we are going to lay the foundation for a simple website
powered by a Node api server. By the end of this series of tutorials, we will
have a Node website with basic user registration and authentication capabilities.
I assume that you have a basic understanding of JavaScript and web development.
You can find the full source code for the project here.
Let’s dive in!

Installing Our Tools

First you will need to install node.js. You can install
it directly from the official website on either
Mac, Linux, or Windows. I am writing this tutorial on a Mac running Node version
6.2.0. While there will be some differences depending on your operating system
of choice, as long as you are on the same version of Node things should work.

Open up your command line and test out the following commands:

$ node -v
$ npm -v

If you see a version number printed out to the screen for both of those commands,
then you are ready to go!

Note that the leading ‘$’ indicates a shell prompt, and not a character that you
need to type in. The commands to run are on each line following the ‘$’, so be
careful not to copy and paste the ‘$’ sign.

Creating Our Project

Create a folder to hold our project called sample_app, and initialize it as a
Node project using the NPM tool:

$ mkdir sample_app
$ cd sample_app
$ npm init

You will be prompted for some information about the project such as author name.
Go ahead and accept the defaults by just hitting enter if you aren’t sure what
to put. Afterwards you should see a new package.json file in your project folder.

My favorite library for creating Node.js servers is Hapi.
Hapi is famous for supporting Walmart’s e-commerce applications under massive
load during black Friday. Install Hapi using the Node Package Manager, or NPM.

$ npm install hapi --save

If you look at the package.json file, you will see that npm added Hapi as a
dependency. That’s what the ‘save’ option does. This will help you keep track
of all the libraries needed to run your project! You will also notice a new
folder called ‘node_modules’. This folder is where npm downloads libraries for
you to use.

Your First Node.js Server

Let’s start writing our first piece of node.js code! Create a file called index.js
with the following content:

Depending on your level of JavaScript experience, some of the syntax in this file
might look a little strange to you. Keywords like ‘const’ and arrow functions
written with ‘() => {}’ are new additions to the most recent official language
standard, ES6 (or ES2015). While ES6 is not fully supported in every browser,
most of it’s features are supported in the newest versions of Node.

Start your server with the following command:

node index.js

You should see a message printed to the screen that says ‘Server running at:
localhost:8000’. Visit localhost:8000 in your web browser to see the message
‘Hello, Node.js!’. Congratulations, you’ve written your first Node.js web app!
You can stop the server by hitting control + c on your keyboard.

Building a Better Project Structure

A realistic project will have more than just one file. Let’s create some better
structure for our application. Add two folders, one called ‘client’ and one called
‘server’. Move the index.js file we made earlier into the ‘server’ folder. Create
an empty file called index.html in the client folder. Finally, create an empty file
called index.js in the sample_app folder. After all is done, your project’s file
structure should look like this:

When you require a folder like this, Node’s module system will automatically look
for a file called index.js within that folder. All this line does is import and
execute the contents of our server/index.js file. This will give us a convenient
way to start our server!

If you open up your package.json file, you will see a section called ‘scripts’.
This is a convenient place to put commands that you run often. Add a ‘start’
script like the code below:

Now you can use npm to start your Node server. Open your command line in the
‘sample_app’ folder and run the following command:

$ npm run start

Just like before, you should see a message printed to the screen that says
‘Server running at: localhost:8000’. Visit localhost:8000 in your web browser
to be sure you still see the message ‘Hello, Node.js!’. Remember that the code
in server/index.js should match the code we wrote in the previous section, ‘Your
First Node Server’.

Remember that you must be in the same directory as the package.json file in order
to run npm commands, and that ours is in the project root; the sample_app
directory.

Adding a Homepage

Node can serve static HTML files just like any web server. Hapi uses a plugin
called Inert to enable this. Install it with NPM:

$ npm install inert --save

Now we can update our code in server/index.js to serve the index.html file for
our home route.

Start you server again by running ‘npm run start’ in the ‘sample_app’ directory.
If you visit localhost:8000 you should see the heading ‘Sample App Homepage’.
Your server can now handle HTML files!

It is worth noting that Hapi can also do more advanced HTML templating with a package
called Vision. You could create dynamic HTML
pages on your server just like other web programming tools such as PHP or Ruby on
Rails. In this guide however we are going to focus on creating an API and will
not cover any server-side templating.

A Demo API

API, or Application Programming Interface, can mean many different things depending
on the context. In these tutorials our API is a web service that can handle creating,
reading, updating, and deleting data. Rather than rendering complete web pages
with web forms to accomplish this, our API will simply send and receive raw data
leaving the display and formatting of this data up to the client app. A ‘client
app’ could be HTML and JavaScript running in a browser, or it could even be an
Android or iPhone application. This is one of the major reasons that API’s have
become popular recently - they are flexible enough to support both web and mobile
apps.

Let’s create a very simple demo of how our API and web app are going to work.
This will just be a quick and easy demo which will be extended in future tutorials
in this series.

Open up server/index.js and update it to match the code below. The key differences
are in the server.route method about halfway down the file.

Restart your server and open localhost:8000/api/messages/ in your browser. You
should see some raw data in a format called JSON, or JavaScript Object Notation.
We’ve structured our data under a key called, appropriately enough, data. The data
is just a list of 3 messages, complete with an ID and the actual text of the message.
While this data is obviously not very nice for a human to read, it is perfect for
a computer program!

Let’s open up client/index.html and add a simple client-side application to read
and format this data a little better for a human user. Update your file to match
the code below:

There’s quite a bit of code here, so let’s go through it step by step. First in
the HTML we added two buttons, one to get the message data from our API, and another
to clear the messages out once we are done with them. Next we added an empty list
to hold the messages we get from the API.

Near the bottom of the HTML page we added some ‘script’ tags to hold our simple
JavaScript application. I decided to link jQuery into our page to help make our
code a bit easier to write. jQuery is one of the most popular libraries in use
on the web today, so hopefully you have seen it before.

I put all our code in a document ready callback which will wait until the page is
loaded before running our code. I grab our two buttons by their ID’s and set up
click handlers to get and clear messages respectively. I also grab our message
list by it’s ID so that we can add our messages to it once we get them. Finally
I define 3 functions; one to get message data from the API, another to format the
message data into an HTML list and add it to the page, and finally one to clear
out the messages once we are done with them.

Restart your server and go to localhost:8000 in your browser to see the simple messages
app. You can press ‘Get Messages’ to populate the list with messages from the API,
and then you can press ‘Clear Messages’ to get rid of them. Right click the page
and select ‘Inspect Element’ to see how the HTML of the page is changing. Click
the ‘Network’ tab of the inspector to see the API request and response made when
you click ‘Get Messages’. Notice how the page does not need to refresh in order
to get the messages! This is how many popular email applications work, which are
able to create, read, and delete emails without ever refreshing the page. All the
data is being managed by JavaScript running in your browser. The application feels
much faster and more responsive when you can avoid refreshing the page.

You can perhaps imagine how you might extend this small application. Right now
all we have are three hardcoded messages, but if we add a database we could easily
manage many more messages. We could add buttons to create new messages and send
them to our API server to be saved to a database. Since each message is rendered
as a list item with an ID, it would be possible to add a ‘Delete’ button to each
message and send a delete request to your API server to tell it to delete the message
from a database. You could potentially add all sorts of messaging functionality
if you wanted! Unfortunately this is where our demo app ends. We will add more
functionality to it in upcoming tutorials.

Next Steps

We have created a very basic Node app with just a homepage. Next we need to give
our app the ability to work with a database. Stay tuned for part 2 where we will
cover using a relational SQL database to store and retrieve data!