Note: This text is a part of Express.js Guide: The Comprehensive Book on Express.js.
An example of an Express.js app using Storify API as a data source is a continuation of introduction to Express.js tutorials.
Note: This text is a part of Express.js Guide: The Comprehensive Book on Express.js.
An example of an Express.js app using Storify API as a data source is a continuation of introduction to Express.js tutorials.
Note: This text is a part of Express.js Guide: The Comprehensive Book on Express.js.
Express.js is one of the most popular and mature Node.js frameworks. You can read more about in Intro to Express.js series on webapplog.com:
To learn how to create an application from scratch please refer to the earlier post.
Express.js is a node.js framework that among other things provides a way to organize routes. Each route is defined via a method call on an application object with a URL patter as a first parameter (RegExp is also supported), for example:
app.get('api/v1/stories/', function(res, req){
...
})
or, for a POST method:
app.post('/api/v1/stories'function(req,res){
...
})
It’s needless to say that DELETE and PUT methods are supported as well.
The callbacks that we pass to get()
or post()
methods are called request handlers, because they take requests (req
), process them and write to response (res
) objects. For example:
app.get('/about', function(req,res){
res.send('About Us: ...');
});
We can have multiple request handlers, hence the name middleware. They accept a third parameter next
calling which (next()
) will switch the execution flow to the next handler:
app.get('/api/v1/stories/:id', function(req,res, next) {
//do authorization
//if not authorized or there is an error
// return next(error);
//if authorized and no errors
return next();
}), function(req,res, next) {
//extract id and fetch the object from the database
//assuming no errors, save story in the request object
req.story = story;
return next();
}), function(req,res) {
//output the result of the database search
res.send(res.story);
});
ID of a story in URL patter is a query string parameter which we need for finding a matching items in the database.
Parameters are values passed in a query string of a URL of the request. If we didn’t have Express.js or similar library, and had to use just the core Node.js modules, we’d had to extract parameters from HTTP.request object via some require('querystring').parse(url)
or require('url').parse(url, true)
functions trickery.
Thanks to Connect framework and people at VisionMedia, Express.js already has support for parameters, error handling and many other important features in the form of middlewares. This is how we can plug param middleware in our app:
app.param('id', function(req,res, next, id){
//do something with id
//store id or other info in req object
//call next when done
next();
});
app.get('/api/v1/stories/:id',function(req,res){
//param middleware will be execute before and
//we expect req object already have needed info
//output something
res.send(data);
});
For example:
app.param('id', function(req,res, next, id){
req.db.get('stories').findOne({_id:id}, function (e, story){
if (e) return next(e);
if (!story) return next(new Error('Nothing is found'));
req.story = story;
next();
});
});
app.get('/api/v1/stories/:id',function(req,res){
res.send(req.story);
});
Or we can use multiple request handlers but the concept remains the same: we can expect to have req.story
object or an error thrown prior to the execution of this code so we abstract common code/logic of getting parameters and their respective objects:
app.get('/api/v1/stories/:id', function(req,res, next) {
//do authorization
}),
//we have an object in req.story so no work is needed here
function(req,res) {
//output the result of the database search
res.send(story);
});
Authorization and input sanitation are also good candidates for residing in the middlewares.
Function param()
is especially cool because we can combine different keys, e.g.:
app.get('/api/v1/stories/:storyId/elements/:elementId',function(req,res){
res.send(req.element);
});
Error handling is typically used across the whole application, therefore it’s best to implement it as a middleware. It has the same parameters plus one more, error
:
app.use(function(err, req, res, next) {
//do logging and user-friendly error message display
res.send(500);
})
In fact, the response can be anything:
JSON string
app.use(function(err, req, res, next) {
//do logging and user-friendly error message display
res.send(500, {status:500, message: 'internal error', type:'internal'});
})
Text message
app.use(function(err, req, res, next) {
//do logging and user-friendly error message display
res.send(500, 'internal server error');
})
Error page
app.use(function(err, req, res, next) {
//do logging and user-friendly error message display
//assuming that template engine is plugged in
res.render('500');
})
Redirect to error page
app.use(function(err, req, res, next) {
//do logging and user-friendly error message display
res.redirect('/public/500.html');
})
Error HTTP response status (401, 400, 500, etc.)
app.use(function(err, req, res, next) {
//do logging and user-friendly error message display
res.end(500);
})
By the way, logging is also should be abstracted in a middleware!
To trigger an error from within your request handlers and middleware you can just call:
next(error);
or
next(new Error('Something went wrong :-(');
You can also have multiple error handlers, and use named instead of anonymous functions as its shows in Express.js Error handling guide.
In addition to extracting parameters, it can be used for many things, like authorization, error handling, sessions, output, and others.
res.json()
is one of them. It conveniently outputs JavaScript/Node.js object as a JSON. For example:
app.get('/api/v1/stories/:id', function(req,res){
res.json(req.story);
});
is equivalent to (if req.story
is an Array and Object):
app.get('/api/v1/stories/:id', function(req,res){
res.send(req.story);
});
or
app.get('api/v1/stories/:id',function(req,res){
res.set({
'Content-Type': 'application/json'
});
res.send(req.story);
});
Middleware is flexible. You can use anonymous or named functions, but the best thing is to abstract request handlers into external modules based on the functionality:
var stories = require.('./routes/stories');
var elements = require.('./routes/elements');
var users = require.('./routes/users');
...
app.get('/stories/,stories.find);
app.get('/stories/:storyId/elements/:elementId', elements.find);
app.put('/users/:userId',users.update);
routes/stories.js:
module.exports.find = function(req,res, next) {
};
routes/elements.js:
module.exports.find = function(req,res,next){
};
routes/users.js:
module.exports.update = function(req,res,next){
};
You can use some functional programming tricks, like this:
function requiredParamHandler(param){
//do something with a param, e.g., check that it's present in a query string
return function (req,res, next) {
//use param, e.g., if token is valid proceed with next();
next();
});
}
app.get('/api/v1/stories/:id', requiredParamHandler('token'), story.show);
var story = {
show: function (req, res, next) {
//do some logic, e.g., restrict fields to output
return res.send();
}
}
As you can see middleware is a powerful concept for keeping code organized. The best practice is to keep router lean and thin by moving all the logic into corresponding external modules/files. This way important server configuration parameters will be neatly in one place, right there when you need them! :-)
After looking at Google Analytics stats I’ve realized that there is a demand for short Node.js tutorial and quick start guides. This is an introduction to probably the most popular (as of April 2013) Node.js framework Express.js.
This app is a start of mongoui project. A phpMyAdmin counterpart for MongoDB written in Node.js. The goal is to provide a module with a nice web admin user interface. It will be something like Parse.com, Firebase.com, MongoHQ or MongoLab has but without trying it to any particular service. Why do we have to type db.users.findOne({'_id':ObjectId('...')})
any time we want to look up the user information? The alternative of MongoHub mac app is nice (and free) but clunky to use and not web based.
Ruby enthusiasts like to compare Express to Sinatra framework. It’s similarly flexible in the way how developers can build there apps. Application routes are set up in a similar manner, i.e., app.get('/products/:id', showProduct);
. Currently Express.js is at version number 3.1. In addition to Express we’ll use Monk module.
We’ll use Node Package Manager which is usually come with a Node.js installation. If you don’t have it already you can get it at npmjs.org.
Create a new folder and NPM configuration file, package.json, in it with the following content:
{
"name": "mongoui",
"version": "0.0.1",
"engines": {
"node": ">= v0.6"
},
"dependencies": {
"mongodb":"1.2.14",
"monk": "0.7.1",
"express": "3.1.0"
}
}
Now run npm install
to download and install modules into node_module folder. If everything went okay you’ll see bunch of folders in node_modules folders. All the code for our application will be in one file, index.js, to keep it simple stupid:
var mongo = require('mongodb');
var express = require('express');
var monk = require('monk');
var db = monk('localhost:27017/test');
var app = new express();
app.use(express.static(__dirname + '/public'));
app.get('/',function(req,res){
db.driver.admin.listDatabases(function(e,dbs){
res.json(dbs);
});
});
app.get('/collections',function(req,res){
db.driver.collectionNames(function(e,names){
res.json(names);
})
});
app.get('/collections/:name',function(req,res){
var collection = db.get(req.params.name);
collection.find({},{limit:20},function(e,docs){
res.json(docs);
})
});
app.listen(3000)
Let break down the code piece by piece. Module declaration:
var mongo = require('mongodb');
var express = require('express');
var monk = require('monk');
Database and Express application instantiation:
var db = monk('localhost:27017/test');
var app = new express();
Tell Express application to load and server static files (if there any) from public folder:
app.use(express.static(__dirname + '/public'));
Home page, a.k.a. root route, set up:
app.get('/',function(req,res){
db.driver.admin.listDatabases(function(e,dbs){
res.json(dbs);
});
});
get()
function just takes two parameters: string and function. The string can have slashes and colons, for example product/:id
. The function must have two parapemets request and response. Request has all the information like query string parameters, session, headers and response is an object to with we output the results. In this case we do it by calling res.json()
function. db.driver.admin.listDatabases()
as you might guess give us a list of databases in async manner.
Two other routes are set up in a similar manner with get()
function:
app.get('/collections',function(req,res){
db.driver.collectionNames(function(e,names){
res.json(names);
})
});
app.get('/collections/:name',function(req,res){
var collection = db.get(req.params.name);
collection.find({},{limit:20},function(e,docs){
res.json(docs);
})
});
Express conveniently supports other HTTP verbs like post and update. In the case of setting up a post route we write this:
app.post('product/:id',function(req,res) {...});
Express also has support for middeware. Middleware is just a request function handler with three parameters: request
, response
, and next
. For example:
app.post('product/:id', authenticateUser, validateProduct, addProduct);
function authenticateUser(req,res, next) {
//check req.session for authentication
next();
}
function validateProduct (req, res, next) {
//validate submitted data
next();
}
function addProduct (req, res) {
//save data to database
}
validateProduct and authenticateProduct are middleware. They are usually put into separate file (or files) in a big projects.
Another way to set up middle ware in Express application is to use use()
function. For example earlier we did this for static assets:
app.use(express.static(__dirname + '/public'));
We can also do it for error handlers:
app.use(errorHandler);
Assuming you have mongoDB installed this app will connect to it (localhost:27017) and display collection name and items in collections. To start mongo server:
$ mongod
to run app (keep the mongod terminal window open):
$ node .
or
$ node index.js
To see the app working, open http://localhost:3000 in Chrome with JSONViewer extension (to render JSON nicely).