version-validator v1.1.1

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