nodify-approute
===============

Connect.js middleware to automagically convert HTTP requests into "live"
JavaScript objects, route them to appropriate functions, then wrap their
responses into HTTP responses. Developers worry about the content of API
requests, not administrivia of converting to/from HTTP responses/requests.

Installation

The easiest way to install this package is to use npm:

    npm install nodify-approute

If you want to check out the source, use the git command:

    git clone git://github.com/nodify/nodify-approute.git

Usage

Initialization

nodify-approute is initialized by passing a route descriptor to the
createInstance() and then call the init function on the instance, passing
a callback function like this:

    var approute = require( 'nodify-approute' );
    var connect = require( 'connect' );
    
    var route_descriptor = {
              :
              :
      insert stuff here
              :
              :
    };
    
    var server = connect();
    var router = approute.createInstance( route_descriptor );
    
    router.init( function ( middleware_function ) {
        server.use( "/app", middleware_function )
    } );

There are two things you should note about this example:
* I totally punted on giving a route descriptor (that's cause they tend to be complicated.
* nodify-approute doesn't do much unless you're using it in conjunction with connect.js (or express.js)

Route Descriptors

Route Descriptors contain arrays of objects describing a route and "method
functions" to execute when requests are received by the connect server. Here's
an example:

    var sessions = [];
    
    var users = {
        "alice": "sekrit",
        "bob": "dingo",
        "chuck": "larb"
    };
    
    var route_descriptor = {
        routes: [
            {
                route: "/",
                get: function( body, params, callback ) {
                    callback( 'No functionality here, try going to /app/login' );
                }
            },
            {
                route: "/login",
                get: function( body, params, callback ) {
                    callback( "You sure you don't want to use POST?" );
                },
                post: function ( body, params, callback ) {         
                    if( body.username && users[ body.username ] ) {
                       if( body.password && users[ body.username ] === body.password ) {
                           sessions.push( {username: body.username} );
                           callback( {success: true, session: '/app/session/' + (sessions.length - 1) } );
                       } else {
                           callback( {success: false, error: 'bad password' } );
                       }
                    } else {
                        callback( {success: false, error: 'bad username'} );
                    }
                }
            },
            {
                route: "/session/([0-9]+)",
                params: ["sessionid"],
                validate: function( params, callback ) {
                    callback( 'undefined' !== typeof sessions[ params.sessionid ] );
                },
                get: function( body, params, callback ) {
                    callback( { success: true, info: sessions[ params.sessionid ] } );
                }
            }
        ]
    };

This descriptor defines three routes: "/", "/login" and "/session/+". Assuming
you called the connect.js use() function with "/app" as the first parameter
(and thus making all routes relative to the "/app" path) executing a HTTP GET
at "/app/" would cause the topmost get: function to execute.

Note that the "/session/+" route includes a regex group; this defines a
parameter. Routes with parameters use the params array in the descriptor to
give names to parameters.

Parameters can be validated by defining a validate() function. The function is
called with a parameters object and a callback. Calling the callback with a
boolean tells nodify-approute whether or not the parameters are valid.