Version Validator

This package will generate middleware to handle version management in your REST API. It is based on the conventions used in restify and allows you to easily create a similar flow in expressjs.

The package will parse the version as follows:

1. Specified in the query parameter version: req.query.version
2. Specified in the header as accept-version: req.headers['accept-version']

The queryString parameter takes precedence over the header

Versions are expected to be expressed as semver queries (the same way you specify npm package versions):

GET /?version=~1.0.0

Installation

npm install version-validator

Usage Examples

Basic

In its most basic form you can use this library to add req.version and req.matchedVersion to your requests

let app = require('express')()
let {validateVersion} = require('version-validator')
const versions = ['1.0.0', '1.1.0', '2.0.0']

app.use(validateVersions(versions))

app.get('*', (req, res) => {
  res.status(200).json({
    version: req.version,
    matchedVersion: req.matchedVersion
  })
})

Routing based on version

The library also exposes a helper function which will route traffic into the chain if it matches, or to the next route if it doesn't

let app = require('express')()
let {isVersion, validateVersion} = require('version-validator')
const versions = ['1.0.0', '1.1.0', '2.0.0']

app.use(validateVersions(versions))

app.get('*', isVersion('1.0.0'), (req, res) => {
  // req.matchedVersion will be '1.0.0' here
  res.status(200).json({
    version: req.version,
    matchedVersion: req.matchedVersion
  })
})

app.get('*', (req, res) => {
  // req.matchedVersion will be '1.1.0' or '2.0.0' here
  res.status(200).json({
    version: req.version,
    matchedVersion: req.matchedVersion
  })
})

Make the version mandatory

By default validateVersion will interprete no version as semver '*'. You can make the version specification mandatory by passing isMandatory: false, in which case it will return an error if the version is missing

app.use(validateVersion{
  isMandatory: true,
  versions: ['1.0.0']
})

Do your own error handling

By default validateVersion will send a reply directly when the version is not supported. However you can have it call the expressjs error handler instead

app.use(validateVersions({
  sendReply: false,
  versions: ['1.0.0']
}))

app.get('*', (req, res) => res.status(200).send('You requested a valid version'))
app.use((error, req, res, next) => res.status(error.status).send('You requested an invalid version'))

You can customize the error that is passed in the callback by giving an error generating function as the generateError parameter:

app.use(validateVersions({
  sendReply: false,
  generateError: () => new Error('my-custom-error')
  versions: ['1.0.0']
}))

app.get('*', (req, res) => res.status(200).send('You requested a valid version'))
app.use((error, req, res, next) => res.status(500).send(error.message))
// error.message will be 'my-custom-error'

API

ErrorGenerator

A function generating a custom error to be passed into next when the version is not valid

Returns error

ValidatorOptions

An object containing the configuration options of the validateVersion function

Properties

• versions Array<string>
• sendReply ?boolean
• isMandatory ?boolean
• sendVersionHeader ?boolean
• generateError ?ErrorGenerator

validateVersion

Generates a middleware to parse and validate versions out of the request

Parameters

• args (ValidatorOptions | Array<string>) An object of options, or an array of supported semver versions

Examples

let app = require('express')();
let vv = require('version-validator');

app.use(vv.validateVersion({
  versions: ['1.0.0'],
  isMandatory: true
}));
app.all('/', (req, res) => res.status(200).json({
  req.version,
  req.matchedVersion
}));

• Throws TypeError Properties of args must have their specified types

Returns Middleware A middleware that validates the requested version and populates req.version and req.matchedVersion

isVersion

Generates a middleware route that routes the request into next() if the version matches and next('route') if the version does not matches

Parameters

• version string A semver string

Examples

let app = require('express')();
let vv = require('version-validator');

app.use(vv.validateVersion(['1.0.0']));
app.all('/', vv.isVersion('1.0.0'), (req, res) => res.status(200).send(`${req.matchedVersion} is 1.0.0`));
app.all('/', (req, res) => res.status(200).send(`${req.matchedVersion} is not 1.0.0`));

• Throws TypeError version must be a valid semver string

Returns Middleware A middleware to route requests for this version