Add support for API versioning

- Refactor Route to support multiple handlers and api versioning.
- Add HeaderApiVersioning and RouteApiVersioning features.
- Refactor Router to forward apiVersioningConfig from Router's config to Route.
- Also resolve feature name in Router to the actual versioning feature.
- Add tests for Router and both versioning features.

Author: mikkoseppa

header-api-versioning/index.js

@@ -0,0 +1,30 @@
+"use strict";
+
+module.exports = function (app, config) {
+    return {
+        /**
+         * Find api version from request header
+         *
+         * @param {Object} req Epxress request object
+         * @returns {number} Api version
+        */
+        findApiVersionFromRequest: function(req) {
+            var pattern = config.pattern;
+            if(!pattern) {
+                throw new Error('pattern not defined in config')
+            }
+
+            var header = req.headers[config.header];
+        
+            if (header) {
+                var results = header.match(new RegExp(pattern));
+        
+                if (results) {
+                    return parseInt(results[1]);
+                }
+            }
+        
+            return undefined;
+        }
+    }
+}

header-api-versioning/tests/header-api-versioning.spec.js

@@ -0,0 +1,51 @@
+var _ = require('lodash')
+  , expect = require('expect.js')
+  , HeaderApiVersioning = require('../index')
+
+describe('Header API versioning', function () {
+  var request;
+  var config;
+  var app;
+  var feature;
+
+  beforeEach(function () {
+    // Mock express app
+    app = {};
+
+    // Mock feature config
+    config = {
+      header: 'accept',
+      pattern: 'application\/vnd.someapplication\.v(\\d+)\\+[A-Za-z]+'
+    };
+
+    // Mock express request object.
+    request = {
+      headers: {
+        'accept': 'application/vnd.someapplication.v1+json'
+      }
+    };
+
+    feature = HeaderApiVersioning(app, config);
+  });
+
+  it('should return api version correctly', function() {
+    var apiVersion = feature.findApiVersionFromRequest(request);
+    expect(apiVersion).equal(1);
+  });
+
+  it('should not return api version with wrong header formatting', function() {
+    request.headers.accept = 'application/vnd.someapplication+v1.json'
+    var apiVersion = feature.findApiVersionFromRequest(request);
+    expect(apiVersion).equal(undefined);
+  });
+
+  it('should throw an exception if pattern is not defined in config', function() {
+    delete config.pattern;
+    feature = HeaderApiVersioning(app, config);
+
+    expect(function() {
+      feature.findApiVersionFromRequest(request);
+    }).throwError();
+  });
+
+});

route-api-versioning/index.js

@@ -0,0 +1,35 @@
+"use strict";
+
+var _ = require('lodash');
+
+module.exports = function (app, config) {
+    return {
+        /**
+         * Find api version from request header
+         *
+         * @param {Object} req Epxress request object
+         * @returns {number} Api version
+        */
+        findApiVersionFromRequest: function(req) {
+            var apiVersion = req.params.apiVersion;
+            if (apiVersion) {
+                var match = apiVersion.match(new RegExp(_.get(config, 'pattern', 'v(\\d+)')));
+                if (match) {
+                    return parseInt(match[1]);
+                }
+            }
+            return undefined;
+        },
+
+        /**
+         * Generates path for route
+         *
+         * @param {string} path Original route path
+         * @returns {string} Generated route path
+        */
+        generateRoutePath: function(path) {
+            return _.get(config, 'routePattern', '/:apiVersion(v\\d+)?') + path;
+        }
+    }
+
+}

route-api-versioning/tests/route-api-versioning.spec.js

@@ -0,0 +1,86 @@
+var _ = require('lodash')
+  , expect = require('expect.js')
+  , RouteApiVersioning = require('../index')
+
+describe('Route API versioning', function () {
+  var request;
+  var config;
+  var app;
+  var feature;
+
+  describe('default configuration', function() {
+    beforeEach(function () {
+      // Mock express app
+      app = {};
+  
+      // Mock express request object.
+      request = {
+        params: {
+          apiVersion: 'v1',
+          other: 'some'
+        }
+      };
+  
+      feature = RouteApiVersioning(app, {});
+    });
+
+    it('should return api version correctly', function() {
+      var apiVersion = feature.findApiVersionFromRequest(request);
+      expect(apiVersion).equal(1);
+    });
+  
+    it('should not return api version with wrong route formatting', function() {
+      request.params.apiVersion = 'b5'
+      var apiVersion = feature.findApiVersionFromRequest(request);
+      expect(apiVersion).equal(undefined);
+    });
+  
+    it('should generate path correctly', function() {
+      var originalPath = '/some/path';
+      var path = feature.generateRoutePath(originalPath);
+      expect(path).equal('/:apiVersion(v\\d+)?' + originalPath);
+    });
+
+  });
+
+  describe('defined configuration', function() {
+    beforeEach(function () {
+      // Mock express app
+      app = {};
+  
+      // Mock feature config
+      config = {
+        routePattern: '/:apiVersion(cool\\d+)?',
+        pattern: 'cool(\\d+)'
+      };
+  
+      // Mock express request object.
+      request = {
+        params: {
+          apiVersion: 'cool1',
+        }
+      };
+  
+      feature = RouteApiVersioning(app, config);
+    });
+
+    it('should return api version correctly', function() {
+      var apiVersion = feature.findApiVersionFromRequest(request);
+      expect(apiVersion).equal(1);
+    });
+  
+    it('should not return api version with wrong route formatting', function() {
+      request.params.apiVersion = 'v5'
+      var apiVersion = feature.findApiVersionFromRequest(request);
+      expect(apiVersion).equal(undefined);
+    });
+  
+    it('should generate path correctly', function() {
+      var originalPath = '/some/path';
+      var path = feature.generateRoutePath(originalPath);
+      expect(path).equal(config.routePattern + originalPath);
+    });
+
+  });
+
+});

route/index.js

@@ -88,10 +88,16 @@ module.exports = function (app, config) {
     var rootPath = module.module.rootPath || '/'
       , expressRouter
       , router = routers[rootPath];
+    
+    var apiVersioningConfig = _.cloneDeep(config.apiVersioning);
+    // Replace api versioning feature name with the actual feature instance
+    if (apiVersioningConfig && apiVersioningConfig.enabled === true) {
+      apiVersioningConfig.feature = app.feature(apiVersioningConfig.feature);
+    }
 
     if (!router) {
       expressRouter = express.Router();
-      router = new Router(expressRouter, config.defaultAuthHandler, config.unauthenticatedStatusCode);
+      router = new Router(expressRouter, config.defaultAuthHandler, config.unauthenticatedStatusCode, apiVersioningConfig);
 
       if (!testing) {
         router = addLoggingToRouter(router, rootPath);