hapi-hydra

hapi-hydra

• Server decorations
  • server.routev([options])
• Options
• Example

This is a hapi plugin to manage three forms of versioning. It was inspired by Your API versioning is wrong, which is why I decided to do it 3 different wrong ways. This plugin makes it simple to implement all three methods of API versioning described in the article.

• URL versioning
• custom header
• Accept header

The accept header must contain version=<version>, for example: curl -i http://localhost:3000/api/bar -H 'Accept: version=v2'

Plugin version 1.x works for hapi 16.x

Server decorations

The plugin decorates the server with a methods for adding routes.

server.routev([options])

The options are the same as the route configuration object with the following additions:

• version - the version of the route. [default: 'v1']
• isDefault - the default version of the route. This route, without version prefix, will invoke the appropriate version of the route. [default: false]

Options

The following plugin options are available:

• header (string/array) - the custom header(s) to look at in order to choose which endpoint to invoke. Returns version for first match.
• responseHeader - response header to indicate which version of the route was invoked. [default: 'version']
• prefix - prefix for the route [default: '/']
• redirect - whether the plugin should rewrite the url or redirect the user with a 302 to the new endpoint [default: false]

Example

const Hapi = require('hapi');
const Hoek = require('hoek');
const HapiVersion = require('./lib');
const Blipp = require('blipp');

const server = new Hapi.Server();
server.connection({ port: 3000 });

server.register([Blipp, { register: HapiVersion, options: { prefix: '/api', redirect: true } }]);

server.routev({ version: 'v1', isDefault: true, method: 'GET', path: '/', handler: (request, reply) => {

    return reply('foo');
} });

server.routev({ version: 'v1', isDefault: false, method: 'GET', path: '/bar', handler: (request, reply) => {

    return reply('foo');
} });

server.routev({ version: 'v2', isDefault: true, method: 'GET', path: '/bar', handler: (request, reply) => {

    return reply('bar v2');
} });

server.start((err) => {

    Hoek.assert(!err, err);
});

The code above makes the following routes available:

*  GET    /api             # alias of /api/v1
*  GET    /api/bar         # alias of /api/v2/bar
*  GET    /api/v1
*  GET    /api/v1/bar
*  GET    /api/v2/bar