node package manager


Exceptionally featureful RESTful web services middleware for Connect.

CONNECT-REST - Exceptionally featureful Restful web services middleware for connect node.js

Join the chat at npm version Code Climate

Important : connect-rest >v1.0 is compatible with connect >v3.0. All examples/tests are complying with this rule!

For connect v2, please use the version 0.9.14 of connect-rest!

From version 2.0.0 connect-rest requires NodeJS 4.0.0 or higher!

Version 1.7.0 is not fully compatible with 1.6.x and below due to the redesigned protector concept.



connect-rest is a featureful very easy-to-use middleware for connect for building REST APIs. The library has a stunning feature list beyond basic rest functionality.

Just a few examples: (far from incomplete):

  • execution branches: a single service can have multiple paths and handlers
  • versioning: rest services can be versioned via many ways
  • regular expressions: path description can be given using regular expression
  • parameter mappings: path matchings can be bound as parameters
  • proxy services: proxying incoming requests to a remote point passing parameters, headers as you request
  • service discovery: built-in rest service allowing one to discover what rest services are available in general or for a given version
  • "reflective" publishing: by providing a single object, its methods will be published as rest services automatically by simple logic
  • dynamic API protection by Protectors
  • Multiple contexts for flexible orchestrating
  • customizable HTTP-layer management: HTTP status code, mime-types, headers, minifying can be set at service and execution level
  • async services: a rest service can call back asynchronously when the answer is made
  • multiple return format: handlers may return with strings, objects, streams and buffers, connect-rest will manage them adequately.

!Note: connect-rest's concept is to provide a feature-full high-level connect middleware for your rest services carrying only about content and business logic, nothing else. However, in case of need for interoperability, the need might cause you to use only the path-related features alone. This can be done using dispatchers.


The connect-rest is a simple, yet powerful middleware for connect, inspired by restify. The aim is to give a really feature-rich tool allowing you to focus on the business logic only.


$ npm install connect-rest


Quick setup

// requires connect and connect-rest middleware 
var connect = require('connect'),
bodyParser = require('body-parser')
var Rest = require('connect-rest')
// sets up connect and adds other middlewares to parse query, parameters, content and session 
// use the ones you need 
var connectApp = connect()
    .use( bodyParser.urlencoded( { extended: true } ) )
    .use( bodyParser.json() )
// initial configuration of connect-rest. all-of-them are optional. 
// default context is /api, all services are off by default 
var options = {
    context: '/api',
    logger:{ file: 'mochaTest.log', level: 'debug' },
    apiKeys: [ '849b7648-14b8-4154-9ef2-8d1dc4c2b7e9' ],
    // discover: { path: 'discover', secure: true }, 
    // proto: { path: 'proto', secure: true } 
var rest = Rest.create( options )
// adds connect-rest middleware to connect 
connectApp.use( rest.processRequest() )
// defines a few sample rest services 
rest.get('/books/:title/:chapter', functionN0 ) { path: '/make', version: '>=1.0.0' }, functionN1 ); [ '/act', '/do' ], functionN2 ); [ { path: '/shake', version: '>=2.0.0' }, { path: '/twist', version: '>=2.1.1' } ], functionN3 );

Back to Feature list


direct binding

You can assign your rest modules by specifying the needed http request functions: head, get, post, put, delete.


function service( request, content, callback ){
    console.log( 'Received headers:' + JSON.stringify( request.headers ) );
    console.log( 'Received parameters:' + JSON.stringify( request.parameters ) );
    console.log( 'Received JSON object:' + JSON.stringify( content ) );
    callback(null, 'ok');
} [ { path: '/shake', version: '>=2.0.0' }, { path: '/twist', version: '>=2.1.1' } ], service );

assign function

Other way to assign is to use the assign function directly.


function service( request, content, callback ){
// bind the service funciont to all http request types 
rest.assign( '*', [ { path: '/shake', version: '>=2.0.0' }, { path: '/twist', version: '>=2.1.1' } ], service );
// bind the service funciont to only the given http request types 
rest.assign( ['head','get','post'], [ { path: '/shake', version: '>=2.0.0' }, { path: '/twist', version: '>=2.1.1' } ], service );

Reflective assignement

See chapter for details: Reflective publishing


After each assign function you might need to pass the followings:

Path description

connect-rest supports many options to be used as path description.

Of course simple paths can be defined as follows:

rest.get('/user/profile', functionN0 );

But I guess you are interested in more complex solutions. Please, fing them below:

Regular expression

rest.get( /^\/[tT]([a-zA-Z]){4}$/g, functionN0 );

This will match to URIs of '/api/tAbba' but won't to '/api/t1abcd8'.

Named parameters

rest.get('/books/:title', functionN0 );


rest.get('/books/:title/:chapter', functionN0 );

You can define parametrized paths for services to accept REST variables from the caller. In this case, whatever string is after the 'books', will be interpret as variable(s) and passed to the service function via the request object.

So sending a get request to the uri '/api/books/AliceInWonderland/1', will result the following request object:

{"headers": ...,"parameters":{"title":"AliceInWonderland", "chapter": "1"}}

Optional parameter'/store/?id', functionN );

This definition allows you to define one optional parameter at the end of the path. It might be called using


or using


paths. Both HTTP calls will be directed to the same functionN service. In latter case, the '108' will be set as a parameter in the request object with the value of '108'.

General matcher

rest.get('/inquire/*book', functionM );

This definition gives you the possibility to define a general matcher allowing to have been called with anything after the string


so can be called using


or using


paths. This results to have the parameter 'book' with value

'alice/in/wonderland' or 'oz/the/great/wizard'


You can make rather complex mixtures of those options as well:


One can call this with uri:

'borrow/2/AliceInWonderland' or 'borrow/2/HG1232131/AliceInWonderland'

The character '*' can be used for both path and version too to make generic bindings:

{ path: '*', version: '*' }

Be aware, that this path will be matched to all paths within the defined context.

Range matcher

rest.get( '/convert/@format', function( request, content, callback ){
    return callback( null, 'ok' );
}, { format:[ 'euro', 'usd', 'huf' ] } );

This definition creates a rest service answering to GET requests if the format part of the URI is contained by the array in the option object. The character '@' tells the connect-rest to match the parameter 'format' to the array called by the same name.

By calling this service with the following URI '/api/convert/usd' will be executed, but calling with '/api/convert/gbp' no rest will be called and 404 will be returned.

Special assigns:

You can use the all options above at once.

[ { path: '/rent/:country/?isbn/*bookTitle', version: '<2.0.0' }, { path: '/borrow/:uid/?isbn/?bookTitle', version: '>=2.1.1' } ]

Just define what you really need. :)

Parameter processing

The logic how connect-rest is managing parameter replacement is the following:

The parameters are processed in the path definition order and any missing optional parameter will be filled with empty strings to keep the order of them keeping in sight all mandatory parameters put after the optional ones.


As for versioning, the syntax is semantic versioning, the same you use for npm

rest.get( { path: '/special', version: '1.0.0' }, functionN0);

So you can use different version specificaiton depending on your need:

version: '1.0.0 - 2.9999.9999'
version: '2.0.1'
version: '2.x'
version: '~1'
version: '>=1.0.2 <2.1.2'

Only the requests defining the right version number will match the defined paths.

connect-rest ignores all unmatching calls which might fail by the badly given path or version.

Back to Feature list

Rest functions

A rest function is a normal JS function you can define easily.

Every handler function receives

  • a 'request' object containing "headers", "parameters", "files", "session" properties
  • an optional 'content' object which is the object extracted from the http body's payload.
  • an optional callback function. This is the 'node standard' way to manage callbacks if needed.

If callback is used as third parameter, needs to be called and pass the error or result object. Otherwise the return value of rest functions will be sent back to the client as a json string.

rest.get( { path: '/personal/:uid', version: '1.0.0' }, function( request, content, callback ){
    callback( null, { name: 'John Doe' } );
rest.get( '/purchases/:uid', function( request, content ){
    return { purchases: [ ... ] };

The async way is strongly encouraged to be used unless you have something really computation-free function...

The result object can be the followings:

  • String
  • Buffer
  • Stream
  • Function

Buffers are converted to Strings or JSONs depending on the mime-types. (see the Customize HTTP response )

rest.get('/handlers/buffer', function( request, content, callback ){
    return callback(null, new Buffer( 'ok', 'utf-8') );

Streams are read to a buffer and returned as strings.

rest.get('/handlers/stream', function( request, content, callback ){
    return callback(null, fs.createReadStream( './test/data/answer.text', { encoding : 'utf-8'} ) );

Functions must be async, the callback of their execution must define the String to be sent back.

rest.get('/handlers/function', function( request, content, callback ){
    return callback(null, function( cb ){ cb( null, 'ok' ); } );

Back to Feature list

Proxy Rest Services

One can define proxying REST services easily using connect-rest as follows:

rest.proxy( 'get', '/proxyEmpty', '', { } );

This will create a REST service on path '[context]/proxyEmpty' answering 'GET' calls and proxying all calls to a remote point: ''.

By default all request parameters will be also sent without any modification. You can prevent this if you set the attribute 'ignoreQuery' in the last parameter as follows:

rest.proxy( 'get', '/proxyEmpty', '', { ignoreQuery: true } );

Considering the wide range of REST calls might look like, it could be useful to bypass all headers to the remote site as the following code shows:

rest.proxy( 'get', '/proxyEmpty', '', { bypassHeader: true } );

This will send further all API_KEYS and other header set for a request sent to this service.

Of course the need to use different headers might appear when proxying a request to a remote/foreign point, so you can define your own headers as well:

rest.proxy( 'get', '/proxyEmpty', '', { remoteHeaders: { /* key-pairs here */ } } );

Back to Feature list

Customize HTTP response

If one defines a rest function possessing 3 parameters, the third is the callback allowing 3 parameters to send. The first and second parameters are the conventional error and result objects.

The third one is an object aimed to contain to refine the HTTP response sent back to the client. This includes mime-types, status code, etc.

Status codes

As for status code, all you need to do is this:

Error case:

rest.get( '/invalidPath', function( request, content, callback ){
    var error = new Error('invalid path');
    error.statusCode = 404;
    return callback( error );

Special case when no error occurred, yet the http request's status has to be set:

rest.get( '/special', function( request, content, callback ){
    return callback( null, 'Processing...', { statusCode: 202 } );

Back to Feature list

Response headers

To refine the headers in the response HTML, the way is the same as above: customize the third parameter of the callback function.

rest.get( '/special', function( request, content, callback ){
    return callback( null, 'Content.', { headers: { ETag: "10c24bc-4ab-457e1c1f" } } );

Minify response JSON

You can make the response JSON object minified by passing a single boolean parameter to the callback's third optional parameter:

rest.get( '/special', function( request, content, callback ){
    return callback( null, '{ "key"     :    "value" }', { minify: true } );

This will send


to the client.

Customize answers of REST functions

When assigning routes with rest API you can pass an object too. This object looks like this:

    contentType: ''
    validator: ...

The contentType defines what the given REST service will retrieve. If not given, 'application/json' will be used.

The validator is a function, which can be used to determine if the REST function can be called in a given circumstances or should be ignored. This could mean authorization or ip address validation or other security concern. [ { path: '/shake', version: '>=2.0.0' }, { path: '/twist', version: '>=2.1.1' } ], function( request, content ){
    return JSON.stringify(content);
}, null, { contentType:'application/xml', validator: function(req, res){ return _.contains(req.user.roles, "superuser"); } } );

Back to Feature list

API_KEY management

The option passed to the connect-rest might contain an array enumerating accepted api_keys:

var options = {
    'apiKeys': [ '849b7648-14b8-4154-9ef2-8d1dc4c2b7e9' ]

If property 'apiKeys' is present, the associated array of strings will be used as the list of api keys demanded regarding every incoming calls. So having such option, a call should look like this:


otherwise error response will be sent with status code 401 claiming: 'API_KEY is required.'.

You can restrict access on service-level. When you call

rest.get( { path: '/shake', version: '>=2.0.0' }, function( request, content ){
    return 'OK';
}, { apiKeys:['1234-1234-1234-1234'] } );

That will require to use the API_KEY '1234-1234-1234-1234' when call that REST service. This will help you refine your access control on service basis.

Unprotected REST service

When you are using API_KEYs, you still might want to have 'exceptions'. Functions which can be served out of the border os API_KEY restriction. You can turn off that protection for a given service like this:

rest.get( { path: '/special', unprotected: true }, functionN0);


Protector is a function which can be passed when creating a rest services and decides if a given call is allowed or should be blocked and ignored. So the protector function called in every rest call when the given path is evaluated and matched and boolean return value of the function tells to the connect-rest to allow the rest function's execution to take place or blocked by some security reason.

rest.get( { path: '/special', protector: function( req, res, pathname, path, callback ){ callback(); } }, functionN0);

A protector function receives all parameters to able to respond the query the case requires it. For example an A&A protector should manage the necessary measurements and might drop the request. Remember: it is designed to be async, the callback should be used to notify the connect-rest if the protector handled the request or the process can performed forward. By passing a single exception as first parameter, the REST service won't be called, and it will be considered as "terminated" by the protector itself. You can have such functions to define session-based dynamic protection or differentiate between widely available rest calls and restricted business-sensitive feature.

Back to Feature list


connect-rest uses context uri prefix by default to create a speparated 'namespace' for the rest functions. You can define it dynamically:

rest.context( '/api' ); // means that every rest calls need to be sent to '/api/X' path. 

or through the option object as well when you add the middleware to the connect object:

var options = {
    'context': '/api'
var rest = Rest.create( options );
connectApp.use( rest.processRequest() )

Default context is the '/api' string.

Orchestrating the contexts

The connect-rest also allows you to specify the context at REST function level. This helps if you want to orchestrate your functions using multiple contexts. Let me show you:

rest.get( { path: '/workspace', context: '/pages' }, functionN0);

This REST function can be called by sending a GET request to the address of


This way you can easily manage dynamic templates not being forced to be in the same context as API calls.

You can orchestrate the contexts of your architecture as it pleases you.

Discovery services

connect-rest provides a built-in service: discover. Via a simple get request, it allows you - by specifying a version - to discover the plublished REST apis matching the given version.

var options = {
    'discover: { path': 'discover', secure: true }
var rest = Rest.create( options )
connectApp.use( rest.processRequest() )

This will enable this service - considering the context described above - on the path '/api/discover/:version'. Sending a get request to - let's say - this path


would retrieve all services which can be called using version 3.0.0 (non-versioned and matching versioned services). The returned JSON is the following:


The option secure tells connect-rest if security should be active for this service.

Prototype services

The assign-methods allows you to set an extra object in the third parameter. An object which can be considered as a prototype of the expected parameter of the service when a client wants to make a call. [ { path: '/shake', version: '>=2.0.0' }, { path: '/twist', version: '>=2.1.1' } ], functionN, { prototypeObject: {'title': 'Alice in Wonderland'} } );

That parameter debriefs the client what structure the functionN expects to receive. To activate this feature, first you have to add a new attribute to the options object:

var options = {
    'apiKeys': [ '849b7648-14b8-4154-9ef2-8d1dc4c2b7e9' ],
    'proto: { path': 'proto', secure: true },
    'logger': 'connect-rest'

This 'proto' object tells connect-rest that the given path is accepting requests to retrieve prototypes:


will retrieve the object

{'title': 'Alice in Wonderland'}

because the service

on path '/api/twist' and method 'POST' with version '2.3.0'

can be called and there is an assigned prototype object to it. Giving access method, version and path is mandatory for this feature.

The option secure tells connect-rest if security should be active for this service.

Back to Feature list

Remove services

One can remove a published service by calling the following function:

rest.unpost( '/shake' );

That code removes all REST services which would be fired by calling with the URI '/shake'. The same path matching logic is used to determine if a given REST function should be removed.

Every publishing method available in connect-rest has a removing-pair function:

unpost, undel, unget ... unassign

There is a second parameter if you want to specify the version of the services you would like to remove:

rest.unpost( '/shake', 1.0.0 );

... unlinking the service answering to the given URI with the given version.

Back to Feature list


In the option object passed to the constructor, there is an optional parameter 'logger', which enables the logging functionality:

var options = {
    'apiKeys': [ '849b7648-14b8-4154-9ef2-8d1dc4c2b7e9' ],
    'discoverPath': 'discover',
    'logger': 'connect-rest'


var options = {
    'apiKeys': [ '849b7648-14b8-4154-9ef2-8d1dc4c2b7e9' ],
    'discoverPath': 'discover',
    'logger': loggerInstance

You can set:

  • a string, which will be interpret as the name of the logger seen in the logs, or
  • passing a logger instance to be used. By default, connect-rest is using winston as logging library.

In the absence of 'logger' property, no logs will be made. The connect-rest will use level 'info' for entry and exit points of services and 'debug' for the milestones of all internal processes.

Back to Feature list

Reflective publishing

connect-rest allows you to have an extremely easy and fast way to publish your services.

You can define your own services like this in a file (services.js in this example):

function health( request ){
    return 'ok';
function record( request, content ){
    return 'saved';
} = health;
exports.record = record;

and publish them this way:

var services = require('./services');
rest.publish( services );

This will discover all functions assigned to the exports having a name which conforms the following regular expression:


The logic is simple. If the function has

  • 1 parameter: it will be a 'get' method
  • 2 parameters: it will be a 'post' method

and the path will be its name. So, by executing one single statement you will automatically have the following services:

/health on Get
/record on Post

If you have 100 services defined, then 100 rest api you will have automatically. Nice.

Domain support

connect-rest adds support for domain-based error handling. To the options object you can pass a boolean value requesting the lib to create domain as NodeJS docs defines:

var options = {
    apiKeys: [ '849b7648-14b8-4154-9ef2-8d1dc4c2b7e9' ],
    discoverPath: 'discover',
    protoPath: 'proto',
    logger: 'connect-rest',
    domain: true

or you can have a more sophisticated version by passing a complete object as follows:

var options = {
    apiKeys: [ '849b7648-14b8-4154-9ef2-8d1dc4c2b7e9' ],
    discoverPath: 'discover',
    protoPath: 'proto',
    logger: 'connect-rest',
    domain: {
        closeWorker: function(req, res){... },
        closeRequest: function(req, res){... }

Where the function closeWorker is an optional function which is called when error occurred and supposed to close the current worker instance if app is running in a node cluster.

The function closeRequest is an optional function which is called to close the request object on error if you want to perform custom response message. By default connect-rest sets the error code 500 and returns a simple error message 'There was a problem!'.

Back to Feature list

Answering async rest requests

connect-rest provides a way to serve async rest requests. It might be important - especially between fragmented server-side environment - to call rest services and accept the answer on a specific callback URL specified by the requestor.

The client has to specify a request parameter "callbackURL" possessing the callback URL where the answer has to be sent. Having sent the request, connect-rest will answer it right away with status code 200 and message Ok. and having the result created, it will sent via HTTP POST to the URL given in the HTTP parameters.

This process is performed behind the scenes, you do not have do anything special about it. If that parameter can be found in the HTTP request, the call will be threaten as async request.

Back to Feature list


In some cases, you might face with a situation where other 3rd party connect library has to be used and the case might require for path-related logic to be used. connect-rest is designed to be able to use as simple path processing helper library as well.

connectApp.use( Rest.dispatcher( 'GET', '/dispatcher/:subject', function(req, res, next){
    res.end( 'Dispatch call made:' + req.params['subject'] );
} ) );

This simple code makes is pretty straightforward. In case of a 'GET' HTTP request coming to the url '/dispatcher', the given function is executed. That function can be any third party connect lib you want to use.

Back to Feature list

More examples

I have collected a few examples from some implementations submited by users of connect-rest.

Might help to have a more complete picture about what you can reach and realize with this library. In case of any wanted scenario, please open a ticket and I will happily comply with it.

Example, how to restrict rest api calls to only those who logged in already, meaning to have some session info

var protectBySession = function(req, pathname, version){
    return req.session && req.session.uid;
rest.get( { path: '/model/person', unprotected: true, protector: protectBySession, version: '1.0.0' }, function( request, content, callback ){
    callback( null, personModel );

Example to how define a free-to-call rest function in a very restricted environment. Dynamic templating is a typical scenario, no versioning is needed, nore api_key or session-based protection, must be put on a separate context and result has mime-type of "text/html"

var allower = function(req, pathname, version){
    return true;
rest.get( { path: '/?page/?id', unprotected: true, protector: allower, context: '/pages' }, function( request, content, callback ){
    // render some page 
    renderer.render(,, function(err, res){
        callback( err, res );
    } );
}, { contentType:'text/html' } );

A fairly complex REST path which is needed in some cases and a custom return status code:

rest.get( '/call/:system/?entity/?version/:subject/*', function( request, content, callback ){
    // Do some business logic 
    return callback(null, 'Done.', {statusCode:201} );
}, { contentType:'application/json' } );

In this case you call this path by the following uris:


Not a typical or strictly REST-conform scenario, but you might end up with the need of complex URIs.

Tip: To manage all calls not handled by connect-rest could be also important. The following code demonstrates how to define a small middleware, which is executed when no REST function is matched.

var rest = Rest.create( options )
app.use( rest.processRequest() )
app.use( function(req, res, next){
    // render error page by some renderer... 
    renderer.render( 'error', {}, function(err, html){
        res.writeHead( 500, { 'Content-Type' : 'text/html' } );
        res.end( html );
    } );
} );


(The MIT License)

Copyright (c) 2014 Imre Fazekas

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.





  • 2.0.0: Moved to Node4 and ES6
  • 1.8.0: OPTIONS method supported
  • 1.6.0: REST services can possess own API key set
  • 1.5.0: remove rest function
  • 1.4.0: logging rewritten
  • 1.3.0: range-based mapping added
  • 1.2.x: fixes...
  • 1.2.0: Stream, Buffer and Function can be set as return object
  • 1.1.0: Proxies added
  • 1.0.0: Switch to connect v3!
  • 0.9.x: fixes...
  • 0.9.0: context specification at REST function level is allowed.
  • 0.8.x: fixes...
  • 0.8.0: protector introduced
  • 0.7.7: check function added. Now you can test if a given call would/allowed to take place.
  • 0.7.x: fixes...
  • 0.6.x: fixes...
  • 0.6.0: dispatchers added
  • 0.5.0: minifying services added
  • 0.0.48: An rest service can now be unprotected
  • 0.0.43-47: Various fixes/improvements
  • 0.0.42: Incoming request count monitoring added
  • 0.0.41: listener for populated measurements can be set
  • 0.0.40: monitoring services (bus) added
  • 0.0.3X: minor fixes, refined documentation
  • a case when mandatory parameter follows optional(s) has been fixed
  • 0.0.26-27: async request fix
  • 0.0.23-25: small fix for content type management
  • 0.0.22: response header customization added
  • 0.0.21:
    • async rest calling allowed by passing a http parameter: callbackURL
    • and some logging fixes
  • 0.0.20: callback/next function passed to the services methods can receive third parameter: statusCode setting the http status of the response
  • 0.0.19: assign function introduced for bulk http-method assignments for a given rest function
  • 0.0.18: fixes
  • 0.0.16:
    • better optional parameter handling allowing to use optional parameter chain like: /set/?department/?room
    • rewritten assing services. instead of passing a single validator, one has to pass on optional object: { contentType: '', validator: ...} which allows one to define validator and answer return content mime-type as well.
  • 0.0.15 : Great changes from Joel Grenon, thank you! Standard callbacks introduced, better optional parameter handling and respecting error status code if exists
  • 0.0.14 : Adding grunt project files
  • 0.0.13 : Validator function can be also passed
  • 0.0.12 : Domain (introduced in Node 0.8.0) support added
  • 0.0.11 : First request parameter now has a callback for async rest calls
  • 0.0.10 : Prototyping added
  • 0.0.9 : General path matcher added, optional now marked with '?'
  • 0.0.8 : Other body parsing middlewares are respected
  • 0.0.6 : logging added
  • 0.0.5 : optional parameter added
  • 0.0.4 : API_KEY management added
  • 0.0.3 : discovery managemenet added
  • 0.0.2 : named parameters added
  • 0.0.1 : initial release