(Note: The code for this series is available on Github - To get the code in preparation for this installment, checkout commit: d82adb485a608278b2003415cab536503c40d5d2)

Database Integration

A lot of tutorials wave their hands at this point and assume you have a database connected. Worse, some will have you write stubs and timeouts to simulate connection delays. If you know what you're doing, these can be a quick way to get a screen or feature running. If you're building from the ground up, you're just delaying the inevitable. Plus, if you've never done it before, figuring out how to wire it in later can be a challenge.

MongoDB and mongoose

Earlier in this series we installed MongoDB. Ensure that you have a running copy before continuing. For a GUI front end, I like using MongoHub. Mongoose is an object modeling solution that lets you write simple schema based objects to work between your Node server and your Mongo database. It has hooks for validation, query building and more, and with a healthy plugin ecosystem can do nearly anything you throw at it. We'll only scratch the surface of its feature set.

To install mongoose, run:

npm install mongoose --save  

We'll need to tell our app how to connect to MongoDB. In our server.js file, add

var mongoose = require('mongoose');  

to the dependencies section at the top. Then underneath that, add

mongoose.connect('mongodb://localhost:27017/rlbb');  

If you configured MongoDB to run on another port, edit the above the string. rlbb is the name of our database and will be created if not present. Here is also where we would add things like database username, password, and the like if we had them.

Now, let's create a User model. Under app/models, create user.js

var mongoose = require('mongoose');  
var Schema = mongoose.Schema;

var UserSchema = new Schema({  
    name: String,
    email: {type: String, required: true, index: {unique: true}},
    password: {type: String, required: true, select: false}
});

module.exports = mongoose.model('User', UserSchema);  

Here, we've pulled in our mongoose dependency and created a User Schema object. Mongoose uses the Schema as representation of a MongoDB collection and the base of its functionality. We've defined a name, an email, and a password. Along with the property names, we've defined their SchemaType, in this case, they are all Strings. For email and password, we've also included some additional properties. required indicates that the field must be present to be valid. Other validators include min, max, match, and custom validators can be created. For email, which we will use as our username, we create an index for it, and put a unique constraint on it. For password, we indicate that normal retrieval of this object from the collection should not include the password field. This prevents it from going across the network. When we add authentication later, we will explicitly ask for the password. Finally, we create a mongoose model from the schema and export it.

Our First REST Endpoints

So, we have a model of our User data. We now need a way to retrieve it from and write it to the database. In this app, all of our API URLs will start with /api/ and then follow with the appropriate REST endpoints. For user, we will end up creating:

/api/users

POST - With a POST request, a new user will be created.
GET - With a GET request, this will return all users.

/api/users/:user_id

GET - With a GET request, this will return a single user with an ID that matches :user_id.
PUT - With a PUT request, the user indicated will be updated.
DELETE - With a DELETE request, the user indicated will be deleted.

With just two endpoints, and using the HTTP verbs, we can satisfy our basic CRUD requirements. To define these, we will create an Express router and then have Express use it, much like we did with the static assets directory and the catch all request handler.

Under app/routes, create user.js ¹.

var bodyParser = require('body-parser');  
var User = require('../models/user');

module.exports = function (app, express) {  
    var userRouter = express.Router();

    userRouter.get('/', function (req, res) {
        res.json({message: 'api is loaded'});
    });

    userRouter.route('/users')
        .post(function (req, res) {
            var user = new User();
            user.name = req.body.name;
            user.username = req.body.username;
            user.password = req.body.password;

            user.save(function (err) {
                if (err) {
                    if (err.code === 11000) {
                        return res.json({success: false, message: 'Duplicate username.'});
                    } else {
                        return res.send(err);
                    }
                } else {
                    res.json({message: 'user created'});
                }

            });
        })
        .get(function (req, res) {
            User.find(function (err, users) {
                if (err) {
                    res.send(err);
                }
                res.json(users);
            })
        });

    userRouter.route('/users/:user_id')
        .get(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);
                res.json(user);
            })
        })
        .put(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);

                if (req.body.name) user.name = req.body.name;
                if (req.body.email) user.email = req.body.email;
                if (req.body.password) user.password = req.body.password;

                user.save(function (err) {
                    if (err)res.send(err);
                    res.json({message: 'user updated'});
                });
            });
        })
        .delete(function (req, res) {
            User.remove({_id: req.params.user_id}, function (err, user) {
                if (err) res.send(err);
                res.json({message: 'user deleted'});
            })
        });

    return userRouter;
};

This looks like a lot, but it's fairly straightforward. Let's tackle it a chunk at a time.

var bodyParser = require('body-parser');  
var User = require('../models/user');  

Here will pull in our dependencies. We will use body-parser to get the data that comes with the PUT and POST requests and User is the user model we just created.

    var userRouter = express.Router();

    userRouter.get('/', function (req, res) {
        res.json({message: 'api is loaded'});
    });

Here we create an instance of an Express router. To give us a way to verify our routes have been initialized properly, we create a default route api/ that will respond with a canned message. If there are problems we can use this to see if it is a server or database issue.

userRouter.route('/users')  
        .post(function (req, res) {
            var user = new User();
            user.name = req.body.name;
            user.email = req.body.email;
            user.password = req.body.password;

            user.save(function (err) {
                if (err) {
                    if (err.code === 11000) {
                        return res.json({success: false, message: 'Duplicate username.'});
                    } else {
                        return res.send(err);
                    }
                } else {
                    res.json({message: 'user created'});
                }

            });
        })
        .get(function (req, res) {
            User.find(function (err, users) {
                if (err) {
                    res.send(err);
                }
                res.json(users);
            })
        });

Here we create the api/users route and handle both the POST and the GET cases. In the POST block, we create a new User, set the fields with data from the request body, and save it. Mongoose handles the heavy lifting of creating the query and talking to the database. We perform some basic error-handling, and return an appropriate message to the client.

In the GET block, we call a static model method on User to retrieve all the stored users and return them. Once again, mongoose takes care of the details.

userRouter.route('/users/:user_id')  
        .get(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);
                res.json(user);
            })
        })
        .put(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);

                if (req.body.name) user.name = req.body.name;
                if (req.body.username) user.username = req.body.username;
                if (req.body.password) user.password = req.body.password;

                user.save(function (err) {
                    if (err)res.send(err);
                    res.json({message: 'user updated'});
                });
            });
        })
        .delete(function (req, res) {
            User.remove({_id: req.params.user_id}, function (err, user) {
                if (err) res.send(err);
                res.json({message: 'user deleted'});
            })
        });

Here we create the api/users/:user_id route. Express will take the value in the request that maps to the :user_id section and create a request parameter that we can use. In the GET block, we use mongoose's findById method to retrieve a specific user. In the PUT block, we again retrieve the requested user, update its information with data from the request body, then save it. Finally, in the DELETE block, we use mongoose's remove function to delete the specified user.

Now it's time to wire the router into the server. In server.js, after the static directory declaration, add the following

// already in our file
app.use(express.static(__dirname + '/public'));

// ADD THESE TWO LINES
var userRoutes = require('./app/routes/user')(app, express);  
app.use('/api', userRoutes);

// already in our file
app.get('*', function(req,res){  
    res.sendFile(path.join(__dirname + '/public/index.html'));
});

First we create the routes, by requiring the file and passing it the two needed fields, app and express. (Go back and look at how we declared our router definition and you will see we have these two params listed). Then, we tell our server to use the routes. Remember, order is important. First our static files, then our API routes, and finally the catch all to serve up our home page. If we added our routes after the catch all, they would never be hit.

If we were to run our server now, with nodemon server.js we would be able to get and set users via HTTP. But... we don't have any users yet, and we don't have screens to input data. Any easy solution is to use something like Postman - REST Client for Chrome (all the browsers have similar tools). In the URL field, enter localhost:1337/api and make sure GET is selected in the dropdown. When you hit send, you should see our test message returned in JSON format.

We can do a similar task to add a user. Set the URL to localhost:1337/api/users, the method to POST, select raw for our input data and add

{ "email" : "hireme@brianmajewski.com", name: "Brian M", password: "123456Secure!"}

These are the fields we defined on our User model.

We also need to set our content type, so select Headers, and for name put Content-Type and value put application/json. If we're configured right, you should get a response back saying user created. To see our new user, hit the same URL, with GET, and you should receive a response similar to

[
    {
        "_id": "54e6b162eb2ac61c54e9b80f",
        "email": "hireme@brianmajewski.com",
        "name": "Brian M",
        "__v": 0
    }
]

Notice: Our password is not returned, as we specified in our schema. Experiment with the other routes and verify that you can update and delete users as well.

So there you have the basics for all CRUD operations for your app. Whether you are storing Widgets, Gizmos, Comments, or Reviews, you will follow the same basic pattern. Later, when we add authentication, you'll see how we can enhance mongoose's standard methods to perform extra functionality, such as encrypting the password, before saving the user.

To get the code with these updates checkout commit 18b0d51ee45d966abf9293be9a5fe25c6af8c6a6

Next Steps

With a functional backend in place, we will begin to create our front end web application. We'll look at using Bower to manage dependencies and RequireJS to load modules.

(UPDATE: There was a bug in the PUT block of the /users/:user_id route - username should have been email - This bug was fixed in the Chapter 7 version of the code on Github and in the text above)

Opinions are like birthdays: everyone has one and I heard about yours on Facebook.

Tool Sets and Libraries

This is easily the most opinionated part of this process. I am always open to code changes; hearing the viewpoints of other developers who may have more experience or a different perspective often lead me to change my code. We call it software for a reason. It should be malleable. It should adapt. When it comes to my tools, however, that's a different story.

OS - Mac OS X

Let's get the holy war out of the way. If you use Windows, more power to you. You must like the extra challenges of playing on Expert mode. For me, there are three key reasons I develop on the Mac.

Environment

Most every environment I am going to deploy to is a *nix variant. Having a BASH (or similar) shell integrated into the OS allows me to create workflows that work everywhere I do.

The Cool Kids Use It

Most of the developers and designers that I read and learn from are using it. This isn't simply a case of "me too!" This is a case where I want zero impediments in my way of completing my task. If they recommend a tool or a library or even some non-web-dev related utility, I'd rather be able to copy them than go searching for an equivalent.

Comfort

I've worked on Apple hardware since the Apple][ days. It just makes more sense to me.

So, yeah, use Windows if you want. Good luck with that.

IDE - Jetbrains IntelliJ IDEA (or Webstorm)

I'm maybe a little bit more flexible on this issue, but not by much. As a professional developer who works with a number of different languages and technologies, having a tool that works across all of them is something I find is worth my investment in time and money. I've been using it since Version 1 when I met the original developers at a conference in Prague. It has been my IDE of choice ever since. Any good text editor like Sublime or Atom can be a useful tool with the right setup and plugins. IDEA mostly works out of the box with deep support for things like Node, Angular, Grunt, and the like.

Brew

Brew is "The missing package manager for OS X" and allows you to install and maintain the tools used to develop and build. Get it. Install it. If you like GUIs, get Cakebrew.

Node

We're going to use Node to stand up a web server to serve our REST endpoints and access the database. DO NOT simply go to the website, download the package and install it. You'll end up in a world of hurt, having to run everything as sudo. Use Brew (see above). $ brew install node Should we switch over to io.js? Maybe? This is one of those rat holes I wanted to avoid with this project. Investigating io.js is an endeavor for another day.

MongoDB

Is MongoDB the right database for your application? Who knows? For this project, we want a simple document datastore that has some easy integration with javascript. We could serve up JSON files instead of hitting a datastore, but that doesn't meet the requirements of having a fully functional application from soup to nuts to build off. We can always swap it out for another technology. Again, use Brew to install it.

Next Steps

At this point, we have the makings for a web server that can serve up data. Well, we have the tools anyways. In the next installment, we'll create a project structure and web server we'll use throughout the project.