(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)