Create expressjs middleware to help version routes in a REST API
APACHE-2.0 License
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:
req.query.version
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
npm install version-validator
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
})
})
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
})
})
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']
})
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'