Skip to content


Subversion checkout URL

You can clone with
Download ZIP
liberal JSON-only HTTP request routing for node.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


liberal JSON-only HTTP request routing for node.


Journey's goal is to provide a fast and flexible RFC 2616 compliant request router for JSON consuming clients.


var journey = require('journey');

// Create a Router object with an associated routing table
var router = new(journey.Router)(function (map) {
    map.root.bind(function (res) { res.send("Welcome") });
    map.get(/^trolls\/([0-9]+)$/).bind(function (res, id) {
        database('trolls').get(id, function (doc) {
            res.send(200, {}, doc);
    };'/trolls').bind(function (res, data) {
        sys.puts(data.type); // "Cave-Troll"

require('http').createServer(function (request, response) {
    var body = "";

    request.addListener('data', function (chunk) { body += chunk });
    request.addListener('end', function () {
        // Dispatch the request to the router
        router.route(request, body, function (result) {
            response.writeHead(result.status, result.headers);


You create a router with the journey.Router constructor:

var router = new(journey.Router)(function (map) {
    // Define routes here

The returned object exposes a route method, which takes three arguments: an http.ServerRequest instance, a body, and a callback, as such:

function route(request, body, callback)

and asynchronously calls the callback with an object containing the response headers, status and body:

{ status: 200,
  headers: {"Content-Type":"application/json"},
  body: '{"journey":"Welcome"}'

Note that the response body will either be JSON data, or empty.


Here are a couple of example routes:

// HTTP methods                      // request
map.get('/users')                    // GET    /users'/users')                   // POST   /users
map.del(/^users\/(\d+)$/)            // DELETE /users/45
map.put(/^users\/(\d+)$/)            // PUT    /users/45

map.route('POST',          '/users') // POST        /users
map.route(['POST', 'PUT'], '/users') // POST or PUT /users

map.root                             // GET /
map.any                              // Matches all request'/', {                      // Only match POST requests to /
    assert: function (req) {         // with data in the body.
        return req.body.length > 0;

Any of these routes can be bound to a function or object which responds to the apply method. We use bind for that:

map.get('/hello').bind(function (res) {});

If there is a match, the bound function is called, and passed the response object, as first argument. Calling the send method on this object will trigger the callback, passing the response to it:

map.get('/hello').bind(function (res) {
    res.send(200, {}, {hello: "world"});

The send method is pretty flexible, here are a couple of examples:

                            // status, headers, body
res.send(404);              // 404     {}       ''
res.send("Welcome");        // 200     {}       '{"journey":"Welcome"}'
res.send({hello:"world"});  // 200     {}       '{"hello":"world"}'

res.send(200, {"Server":"HAL/1.0"}, ["bob"]);

As you can see, the body is automatically converted to JSON, and if a string is passed, it acts as a message from journey. To send a raw string back, you can use the sendBody method:


This will bypass JSON conversion.

URL parameters

Consider a request such as GET /users?limit=5, I can get the url params like this:

map.get('/users').bind(function (res, params) {
    params.limit; // 5

How about a POST request, with form data, or JSON? Same thing, journey will parse the data, and pass it as the last argument to the bound function.

Capture groups

Any captured data on a matched route gets passed as arguments to the bound function, so let's say we have a request like GET /trolls/42, and the following route:


Here's how we can access the captures:

map.get(/^([a-z]+)\/([0-9]+)$/).bind(function (res, resource, id, params) {
    res;      // response object
    resource; // "trolls"
    id;       // 42
    params;   // {}


A bound function has the following template:

function (responder, [capture1, capture2, ...], data/params)


Released under the Apache License 2.0

See LICENSE file.

Copyright (c) 2010 Alexis Sellier

Something went wrong with that request. Please try again.