Step 1: Install Node.js

If it’s not already installed on your system, follow the steps below to install Node.js:

1. Go to http://nodejs.org, and click the Install button.
2. Run the installer that you just downloaded. When the installer completes, a message indicates that Node was installed at /usr/local/bin/node and npm was installed at /usr/local/bin/npm. At this point node.js is ready to use.

Step 2: Install MongoDB

If MongoDB is not already installed on your system, refer to the MongoDB QuickStart for platform-specific installation instructions. Here are some quick steps to install MongoDB on a Mac:

1. Go to http://www.mongodb.org/downloads and download the latest OS X 64-bit production release (2.4.2 at the time of this writing).
2. In Finder, double-click mongodb-osx-x86_64-2.4.2.tgz to extract its contents. (Alternatively you can use: tar -zxvf mongodb-osx-x86_64-2.4.2.tgz)
3. Move the mongodb-osx-x86_64-2.4.2 folder to /usr/local (or another folder according to your personal preferences):

   sudo mv -n mongodb-osx-x86_64-2.4.2/ /usr/local/
   

4. (Optional) Create a symbolic link to make it easier to access:

   sudo ln -s /usr/local/mongodb-osx-x86_64-2.4.2 /usr/local/mongodb
   

5. Create a folder for MongoDB’s data and set the appropriate permissions:

   sudo mkdir -p /data/db
   sudo chown `id -u` /data/db
   

6. Start mongodb

   cd /usr/local/mongodb
   ./bin/mongod
   

Step 3: Download the Code

The Node.js code for the Employee Directory RESTful services is available in this GitHub repository. Download it here and unzip the file anywhere on your file system.

Open server.js and routes/employee.js in a code editor. The RESTFul API is defined as follows:

Step 4: Install dependencies (Express Framework and MongoDB driver)

Open package.json in a code editor and note that the application has two dependencies: the Express framework and the MongoDB driver. To install these dependencies, open a command line (terminal window), cd to the directory where you extracted the source code, and type:

npm install

Step 5: Start the server

Make sure MongoDB is started (Step 2 point 6 above) before you start your Node.js server as follows:

node server.js

Step 6: Testing the API in your Browser

• Retrieve all employees

  http://localhost:3000/employees

• Retrieve all employees whose name includes the letter “j”

  http://localhost:3000/employees?name=j

• Retrieve employee with id == 1

  http://localhost:3000/employees/1

• Retrieve employees that are direct reports of employee number 1

  http://localhost:3000/employees/1/reports

Step 7: Test the API with the Employee Directory Client Application

1. Download the source code for the Employee Directory client application available in this repository.
2. Unzip the file anywhere on your file system.
3. Open index.html in your code editor.
4. Comment out the “model-in-memory.js” script, and uncomment the “model-jsonp.js” script to use the JSONP adapter that connects to your Node.js server.
5. Make sure the MongoDB and Node.js servers are started
6. Open index.html in a Browser and test the application

Related Post

Check out this post for another Node.js example with a more complete RESTful API including the ability to add, modify and delete items (POST, PUT, and DELETE HTTP methods).

I’ve always enjoyed building real-time applications. A few years ago, I built the Java back-end for the Tour of California “Tour Tracker”, and over the years, I have also been involved in several real-time Trader Desktop projects that I documented in this blog. So I thought it would be nice to explore the process of building a real-time application with Node.js and Socket.IO.

As an example, we’ll build a simple web analytics dashboard that shows pages being accessed on a web site in real-time. Kind of like the real-time view in Google Analytics.

The basic flow of the app is as follows:

1. The instrumented web application sends a message to the server every time there is a page change within the app.
2. Upon reception, the server processes the message and…
3. … pushes it to the clients who listen for “pageview” messages.

Testing the Hosted Version of the Application

A live version of the application is hosted on Heroku.

1. Open a browser and access http://nodecellar.coenraets.org/dashboard.html
2. Open a different browser window and start the main Node Cellar application: http://nodecellar.coenraets.org
3. Navigate through the application: the dashboard should display each page view.

In the remaining of this article we will go through the steps of building the application from scratch.

First Iteration: Basic Implementation

Node.js and Socket.IO make it easy to implement this type of real-time messaging system. Here is a simple (yet fully functional) implementation of the application:

The Server

In this first implementation, Node.js doesn’t serve the application’s HTML pages. Pages loaded from any domain (or even from the file system) can connect to our message server to send or listen to “pageview” messages.

The Instrumented Web App

Here is an example of an instrumented page with a script that sends a message to the server every time the page is loaded.

As mentioned above, this page can be loaded from any domain or from the file system.

The Real Time Dashboard

Here is a bare-bones implementation of the real-time dashboard application that receives “pageview” messages from the server.

That’s basically all you need to start building a sophisticated user interface with real-time charts, counters, maps, etc.

Testing the Application

1. Make sure you have Node.js and Socket.IO installed
2. Start the Node.js server

   node server

3. Double-click dashboard.html in Finder (Mac) or Explorer (Windows) to open the page in your default browser.
4. Double-click simplepage.html in Finder or Explorer to open the page in your default browser (in a separate window).
5. Refresh simplepage.html repeatedly: the dashboard should display each page view.

Second Iteration: Adding Authorization

The solution described above works fine, but there are some potential security issues we need to address:

1. Any application (from any domain) can send a message to our server.
2. Any application (from any domain) can listen to the messages pushed by our server.

Let’s refine our solution to make sure that only authorized clients can connect to our server. Socket.IO provides two different authorization methods: global authorization and namespace authorization (more info). In both cases, the handshakeData object provides information (headers, IP address, xdomain, etc) that is useful to implement your authorization logic and determine whether or not you want to allow the client to connect. In this application, we will use global authorization and reject all the cross-domain connection attempts:

There are many other ways you can secure your connections, but that discussion is beyond the scope of this article.

Rejecting cross-domain connections means that the application pages now also have to be served by the Node.js server. To put our new authorization policy into practice, let’s add the real-time web analytics capability to the Node Cellar application that I shared in my previous post.

The Server

The server now serves the HTML pages and hosts Socket.IO.

The Instrumented Web App

The following script has been added to index.html to send a “pageview” message to the server every time the page changes.

Notes:

• We actually don’t need to use Socket.IO for this part of the application. The client sends a “pageview” message to the server and doesn’t listen for messages from the server. In other words, this is a traditional client-to-server one-way communication that could be implemented with a traditional Ajax request.
• The onhashchange event is used because Node Cellar is a “Single Page Application”. The entire application runs within a single page (index.html): views are created dynamically at the client-side and injected into or removed from the DOM as you navigate through the application. Only the hash part of the URL changes (without a page refresh) to reflect the current state of the application.

The Real Time Dashboard

The final version of the dashboard is shown in the screenshot at the top of this post. The Socket.IO code didn’t change much since our initial implementation. The final code for dashboard.html is available here.

Testing the Application

1. Make sure you have Node.js and Socket.IO installed
2. Download the source code
3. Uncomment the Socket.IO related script in the head of public/index.html
4. Start the Node.js server

   node serverwithanalytics

5. Open a browser and access http://localhost:3000/dashboard.html
6. Open a different browser window and start the main Node Cellar application : http://localhost:3000
7. Navigate through the application: the dashboard should display each page view.

Source Code

I added the real-time analytics feature to the existing nodecellar repository.

• To start the regular server (without analytics), use:

  node server

• To start the server with analytics, uncomment the Socket.IO related script in the head of public/index.html, and use:

  node serverwithanalytics

Disclaimer

This is a sample application, not a production application. Some trade-offs were made to keep the code generic, simple and readable.

In my previous post, I shared my recent experience building a RESTful API with Node.js, MongoDB, and Express.

In this post, I’m sharing the client application that uses that RESTful API. The Node Cellar application allows you to manage (retrieve, create, update, delete) the wines in a wine cellar database.

The client application is built with Backbone.js and Twitter Bootstrap.

Run the Application

You can run the application here. For obvious reasons, the create, update, delete features have been disabled in this hosted version.

NOTE: Node.js is running on port 3000 on my EC2 Instance. My friend James Ward convinced me to host the application on their service over at Heroku. It’s now running on port 80 at http://nodecellar.coenraets.org. Thanks James!

Server-Side

The details of the Node.js, MongoDB, and Express implementation are documented in my previous post.

Client-Side

In this application, Node.js is used to provide the RESTful services that the client application needs to manipulate the data. Node.js is not used to generate HTML/Views at the server-side. Instead, the Views are created dynamically at the client-side using Backbone.js and Underscore.js templates. They are injected into- and removed from the DOM as needed as you navigate through the application. Node Cellar is a “single page application”.

This is a Node.js and MongoDB powered version of an application I initially posted here with PHP and Java backends. The original post provides some additional Backbone.js context. This Node.js version also provides an improved user experience with the latest version of Twitter Bootstrap (2.1.1), and a responsive layout. It also uses Adobe Edge Web Fonts.

Source Code

The source code is available in this repository on GitHub.

I recently used Node.js, Express, and MongoDB to rewrite a RESTful API I had previously written in Java and PHP with MySQL (Java version, PHP version), and I thought I’d share the experience…

Here is a quick guide showing how to build a RESTful API using Node.js, Express, and MongoDB.

Installing Node.js

1. Go to http://nodejs.org, and click the Install button.
2. Run the installer that you just downloaded. When the installer completes, a message indicates that Node was installed at /usr/local/bin/node and npm was installed at /usr/local/bin/npm.

At this point node.js is ready to use. Let’s implement the webserver application from the nodejs.org home page. We will use it as a starting point for our project: a RESTful API to access data (retrieve, create, update, delete) in a wine cellar database.

1. Create a folder named nodecellar anywhere on your file system.
2. In the wincellar folder, create a file named server.js.
3. Code server.js as follows:

We are now ready to start the server and test the application:

1. To start the server, open a shell, cd to your nodecellar directory, and start your server as follows:

   node server.js

2. To test the application, open a browser and access http://localhost:3000.

Installing Express

Express is a lightweight node.js web application framework. It provides the basic HTTP infrastructure that makes it easy to create REST APIs.

To install Express in the nodecellar application:

1. In the nodecellar folder, create a file named package.json defined as follows:

2. Open a shell, cd to the nodecellar directory, and execute the following command to install the express module.

   npm install

   A node_modules folder is created in the nodecellar folder, and the Express module is installed in a subfolder of node_modules.

Now that Express is installed, we can stub a basic REST API for the nodecellar application:

1. Open server.js and replace its content as follows:

2. Stop (CTRL+C) and restart the server:

   node server

3. To test the API, open a browser and access the following URLs:
   

   Get all the wines in the database:	http://localhost:3000/wines
   Get wine with a specific id (for example: 1):	http://localhost:3000/wines/1

Using Node.js Modules

In a large application, things could easily get out of control if we keep adding code to a single JavaScript file (server.js). Let’s move the wine-related code in a wines module that we then declare as a dependency in server.js.

1. In the nodecellar folder, create a subfolder called routes.
2. In the routes folder create a file named wines.js and defined as follows:

3. Modify server.js as follows to delegate the routes implementation to the wines module:

4. Restart the server and test the APIs:
   

   Get all the wines in the database:	http://localhost:3000/wines
   Get wine with a specific id (for example: 1):	http://localhost:3000/wines/1

The next step is to replace the placeholder data with actual data from a MongoDB database.

Installing MongoDB

To install MongoDB on your specific platform, refer to the MongoDB QuickStart. Here are some quick steps to install MongoDB on a Mac:

1. Open a terminal window and type the following command to download the latest release:

   curl http://downloads.mongodb.org/osx/mongodb-osx-x86_64-2.2.0.tgz > ~/Downloads/mongo.tgz

   Note: You may need to adjust the version number. 2.2.0 is the latest production version at the time of this writing.

2. Extract the files from the mongo.tgz archive:

   cd ~/Downloads
   tar -zxvf mongo.tgz

3. Move the mongo folder to /usr/local (or another folder according to your personal preferences):

   sudo mv -n mongodb-osx-x86_64-2.2.0/ /usr/local/

4. (Optional) Create a symbolic link to make it easier to access:

   sudo ln -s /usr/local/mongodb-osx-x86_64-2.2.0 /usr/local/mongodb

5. Create a folder for MongoDB’s data and set the appropriate permissions:

   sudo mkdir -p /data/db
   sudo chown `id -u` /data/db

6. Start mongodb

   cd /usr/local/mongodb
   ./bin/mongod

7. You can also open the MongoDB Interactive Shell in another terminal window to interact with your database using a command line interface.

   cd /usr/local/mongodb
   ./bin/mongo

   Refer to the MongoDB Interactive Shell documentation for more information.

Installing the MongoDB Driver for Node.js

There are different solutions offering different levels of abstraction to access MongoDB from Node.js (For example, Mongoose and Mongolia). A comparaison of these solutions is beyond the scope of this article. In this, guide we use the native Node.js driver.

To install the the native Node.js driver, open a terminal window, cd to your nodecellar folder, and execute the following command:

npm install mongodb

Implementing the REST API

The full REST API for the nodecellar application consists of the following methods:

To implement all the routes required by the API, modify server.js as follows:

To provide the data access logic for each route, modify wines.js as follows:

Restart the server to test the API.

Testing the API using cURL

If you want to test your API before using it in a client application, you can invoke your REST services straight from a browser address bar. For example, you could try:

• http://localhost:3000/wines

You will only be able to test your GET services that way. A more versatile solution to test RESTful services is to use cURL, a command line utility for transferring data with URL syntax.

For example, using cURL, you can test the Wine Cellar API with the following commands:

• Get all wines:

  curl -i -X GET http://localhost:3000/wines

• Get wine with _id value of 5069b47aa892630aae000007 (use a value that exists in your database):

  curl -i -X GET http://localhost:3000/wines/5069b47aa892630aae000007

• Delete wine with _id value of 5069b47aa892630aae000007:

  curl -i -X DELETE http://localhost:3000/wines/5069b47aa892630aae000007

• Add a new wine:

  curl -i -X POST -H 'Content-Type: application/json' -d '{"name": "New Wine", "year": "2009"}' http://localhost:3000/wines

• Modify wine with _id value of 5069b47aa892630aae000007:

  curl -i -X PUT -H 'Content-Type: application/json' -d '{"name": "New Wine", "year": "2010"}' http://localhost:3000/wines/5069b47aa892630aae000007

Next Steps

In my next post, I’ll share a client application that makes use of that API. Update: The “next post” is now available here.