api-routes

node-api-routes

A declarative system for creating express API routes. It has a few goals:

• Make declaring routes really easy to create, read, and manage.
• Allow all the usual express helpers (middleware, parameters, etc)
• Be RESTful and create OPTIONS endpoints to help developers.

Install & Usage

npm install api-routes --save

In your express app declaration:

var Api = require('api-routes');
var api = new Api('/api' /* base route */);

// You can add routes right here
api.endpoint('base', {
	url: '',
	help: 'Base route',
	get: function (req, res) {
		res.send({method:'get', endpoint: 'base'});
	}
});

// Or use the more organized requireAll
// See below for examples on how files should be organized.
api.requireAll({
	// Same options as require-all package
	dirname: __dirname + '/routes',
  filter      :  /(.*)\.js$/, // optional
  excludeDirs :  /^\.(git|svn)$/ //optional
});

// Setup the middleware
app.use(api.router);

Examples

Checkout the examples.

An entire route file may look like this:

module.exports = function (api) {

	api.endpoint('test', {

		// Give it a url
		url:'/test',

		// Give it a hint (its in the OPTIONS response)
		help: 'Test endpoint.',

		// Add as many extra fields as you'd like (also included in OPTIONS)
		seealso: '/my-other-route',

    // middleware for every request (and every inherited request)
    middleware: [ someMiddleware(), someOtherMiddleware() ],

    // middleware for only POST, PUT, and DELETE
    edit_middleware: [ someAuthMiddleware() ],

		// Set the method handlers
		get: function (req, res) {
			res.send('gotten');
		},
		post: function (req, res) {
			res.send('posters');
		},
		delete: [
      someExtraMiddleware(),
      function (req, res) {
  			res.send('beleted!');
  		}
    ]
	});

};

Then we can query it like so:

$ curl localhost:8000/api/test
gotten
$ curl localhost:8000/api/test -XPOST
posters
$ curl localhost:8000/api/test -XDELETE
beleted!
$ curl localhost:8000/api/test -XOPTIONS
{
	"help": "Test endpoint.",
	"url": "/test",
	"seealso": "/my-other-route",
	"name": "test",
	"available": [
		"get",
		"post",
		"delete"
	]
}

Easy URL Sub-Paths via Inheritance

Let's imagine you want the following endpoints: /users, /users/:id, /users/:id/profile_pic, users/:id/reputation

Using inheritance, you can set this up cleanly:

module.exports = {
    api.endpoint('users', {
        url: '/users',
        post: function(req, res) {}
    })

    api.endpoint('users.user', {
        url: '/:id',
        get: function(req, res) {}
    })

    api.endpoint('users.user.pic', {
        url: '/profile_pic',
        get: function(req, res) {}
    })

    api.endpoint('users.user.reputation', {
        url: '/reputation',
        get: function(req, res) {}
    })
}

License

MIT License found in LICENSE file.