express-rest-api-router v0.5.3

express-rest-api-router

A router that automatically verifies incoming parameters while creating a json document of all available endpoints.

Features:

• Checks if all required parameters are set on an endpoint
• Automatically sets default values for missing parameters
• Generates a json map of all endpoints for documentation
• Supports nested documents for json POST bodies,
• Customizable error handler per router and for each endpoint

It's probably easier to just show an example of what the router does.

Example configuration:

var Router = require('express-rest-api-router);

var router = Router();

router.get('/endpoint', {
    description: 'An example endpoint',
    params: {
        name: 'string'
    }
}, (req, res) => {
    res.end('hello ' + req.args.name); 
});

app.use(Router);

With the default configuration this is the output of the different requests to the server:

http://myhost/endpoint =>

Status Code 422

http://myhost/endpoint (developer mode) =>

Status Code 422 
{ 
    "error": "Required parameters are missing",
    "params": {
        "name": {
            "type": "string",
            "error": "not set"
        }
    }
}

http://myhost/endpoint?name=bob => hello bob

http://myhost/ =>

Status Code 200
{
    "/endpoint": {
        "GET": {
            "description": "An example endpoint",
            "params": {
                "name": {
                    "type": "string",
                    "required": true,
                    "default": undefined
                }
            }            
        }
    }
}

API

Router(configuration)

The router comes with sensible default values preconfigured, but various behavior can be overridden through the configuration

var Router = require('express-rest-api-router);
var router = Router({
    prefix: '/path'                                     // A prefix for the api map that will be prepended when printing it via router.api or router.endpoints
    error: (value, req, res, next) => {},               // A global error handler that overrides the default behavior
    success: (value, req, res, next) => {},             // A success error handler that overrides the default behavior
    validate: (value, req, res, next) => {},            // A global validator the overrides the default behavior
    paramMap: 'arguments',                              // The property on the request object on which to find parsed parameters
    paramOrder: ['body', 'query', 'params', 'coookies'] // The order in which request properties are searched for incoming parameters
                                                        // Once a parameter has been found it's not going to be overwritten by other properties
});

Router.api(req, res);

A standard request handler implementation that will respond with the currently configured api for this router. Can be used to make it easier for developers to work with your API.

app.get('/', router.api);
// => responds via res.jsonp() and prints current endpoint configuration

The api handler supports multiple formats that can be specified either through a get or path paramter named format:

app.get('/api/:format', router.api);
// => can respond to e.g. /api/tree or /api?format=tree (which doesn't require the path variable).

The supported formats are json (default), tree, table, csv, xml

Router.endpoints;

A map with the configuration of all the endpoints on this Router. Use this to build your own custom api handlers or to do more advanced configuration.

console.log(router.endpoints)
// => { "path": { "method": { "description": "endpoint description", "params": {}}}}

Router.(endpoint, configuration, ...handler);

The router supports all routing verbs that the standard express router supports, including get,post,put,delete, and all. The method calls still behave the exact same way as before only that a configuration object is passed in as well.

Example:

var configuration = {} // See API reference for Configuration
var listHandler = (req, res, next) => {};

Router.post('/list', configuration, listHandler);

Configuration

The configuration is where most of the work needs to be done to get the router working the way you want:

Router.description

A simple string field that allows to set a description of the endpoint.

{
    description: 'A description of the endpoint that is printed in the json map'
}

Router.params

An object that describes the expected parameters for this endpoint. Each parameter is defined as a property of the params object. The parameter definition supports either a simple string definition in the format of type(default) or type(default):

{
    params: {
        aReqioredNumber: 'number',
        anOptionalString: 'string(bob)',
        aRequiredArray: 'string[]',
        anOptionalArray: 'bool[](true, false, false)
    }
}

or a more complex format as an object with more options:

{
    params: {
        name: {
            type: 'string',
            default: 'bob',
            required: false,
            description: 'The users name'       
            min: 3,                                         // min characters for string, min value for number, ignored for boolean
            max: 10,                                        // max characters for string, min value for number, ignored for boolean
            validate: (value, cb) => { cb(err, value); }    // Function to override validation behavior
            error: (error, req, res, next) => {}            // Function to override error behavior
            success: (null, req, res, next) => {}           // Function to trigger on success, does not override request handler
        }
    }
}

Valid types that can be used are: bool, number, string. Arrays of each type can also be used: bool[], number[], string[].

Support for complex objects is only possible in body requests and is tbd. (no support in this plugin so far)

For more examples check out router.test.js the test directory