hapi.js plugin for API versioning
Switch branches/tags
Nothing to show
Clone or download
Latest commit 73e3575 Apr 9, 2017

README.md

npm version Build Status

Consistency

A hapi.js plugin for versioning your API. Borne out of this talk: http://www.slideshare.net/shakefon/hapidays-2014

Installation

npm install consistency

Register plugin with your hapi application, provide the option(s) required for version detection.

server.register({
  register: require('consistency'),
  options: {
    uriParam: 'apiVersion',
    acceptNamespace: 'consistencyExample',
    customHeaderKey: 'api-version'
  }
}, function (err) {
  if (err) console.log('Consistency plugin failed to load');

});

or, via Glue and manifest:

var manifest = {
  connections: [...],
  plugins: {
    consistency: {
      uriParam: 'apiVersion',
      acceptNamespace: 'consistencyExample',
      customHeaderKey: 'api-version'
    }
  }
};

Glue.compose(manifest, function (err, server) {
  ...
});

Versionize your Routes

Array of handlers

server.route({
  id: 'array',
  method: 'GET',
  path: '/array',
  handler: {
    versioned: [
      function(request, reply) {
        reply({
          version: '1.0'
        });
      },
      function(request, reply) {
        reply({
          version: '2.0'
        });
      }
    ]
  }
});

Object of handlers

server.route({
    id: 'object',
    method: 'GET',
    path: '/object',
    handler: {
      versioned: {
        'v1.0': function(request, reply) {
          reply({
            version: '1.0'
          });
        },

        'v2.0': function(request, reply) {
          reply({
            version: '2.0'
          });
        },

        'v1.5': function(request, reply) {
          reply({
            version: '1.5'
          });
        }
      }
    }
});

Version Matching

A version can be provided with or without the v prefix and can also be provided using the latest keyword which will use the latest versioned endpoint.

Matching of version handlers is cached to remove redundent checks based on the route method and route path.

If an endpoint has not changed in a specific version of the api, we can omit it and the matcher will use the version that is closest to the one request. for example if in version 2 we didn't update the users endpoint a request would return version 1

If you provide the version in shorthand (v1, 1) it will return greatest version available for that api version. for example given the versions 1, 1.2, 1.5 providing 1 will return 1.5.