express-request-version
v2.2.0
Published
Request versioning middleware for express.
Downloads
330
Maintainers
Readme
Express Request Version
This middleware allows a version property to be added to an express request object and provides basic version validation.
The resulting version will exist in the req.version
property of all request objects.
In the case of semver routing a best effort is made to match the requested version with
the supported versions. The original requested version will be placed in req.origVersion
.
Usage
Version by path
Versions can be detected by path:
var setVersion = require('express-request-version').setByPath;
// Sets version for paths like /base/v1/thing.
app.use(setVersion('/base/'));
Version by semver path
Versions can be detected by semvers in the path:
var setVersion = require('express-request-version').setBySemverPath;
// Sets version for paths like /base/^v1.0.0/thing.
app.use(setVersion(['v1.0.0', 'v1.1.1', 'v2.0.0'], '/base/'));
Version by accept header
Versions can be detected by accept header:
var setVersion = require('express-request-version').setByAccept;
// Sets version for accept headers like application/vnd.myorg::1+xml.
app.use(setVersion('vnd.myorg', '::', '+xml'));
// Sets version for accept headers like application/vnd.myorg::1+json.
app.use(setVersion('vnd.myorg', '::');
Version by accept semver header
Versions can be detected by accept header with semvers:
var setVersion = require('express-request-version').setBySemverAccept;
// Sets version for accept headers like application/vnd.myorg::^1.0.0+xml.
app.use(setVersion(['v1.0.0', 'v1.1.1', 'v2.0.0'], 'vnd.myorg', '::', '+xml'));
// Sets version for accept headers like application/vnd.myorg::~1.0.0+json.
app.use(setVersion(['v1.0.0', 'v1.1.1', 'v2.0.0'], 'vnd.myorg', '::');
Version validation
You can define a set of supported versions, and raise an error if a request is made with an unsupported version:
var validateVersion = require('express-request-version').validateVersion;
// Will call next with an error if a request is made with a version other than
// one of those listed here.
app.use(validateVersion([ 'v1', 'v1.1', 'v1.1.1', 'v2' ]));
Helper function
In your controller files, you can add support for multiple versions by importing the
multiVersion
helper:
var multiVersion = require('express-request-version').multiVersion;
...
router.get(
'/myPath',
[other middleware],
multiVersion({
'*': version1,
'v0.1.0': version2,
}))
function version1(req, res) {
res.send('This is version 1!')
}
function version2(req, res) {
res.send('This is version 2!')
}
Note that a default version marked with '*'
is mandatory.
API
setByPath(pathPrefix = '/')
- Returns an express middleware that appends a version property to the request object based on path.pathPrefix
- Optional. A path fragment that appears before the version. Must end with a/
.
setBySemverPath(supportedVersions, pathPrefix = '/', preventPrereleaseLock = false, prereleaseMessage = PRERELEASE_MESSAGE)
- Returns an express middleware that appends a matched version and requested version property to the request object based on path.supportedVersions
- An array of versions that are supported.pathPrefix
- Optional. A path fragment that appears before the version. Must end with a/
.preventPrereleaseLock
- Optional. Set to true if you wish to prevent consumers from locking to a prerelease version. If this is set to true and a locked prerelease is requested the server will respond with a 400. Defaultfalse
prereleaseMessage
- Error message to set if a consumer requests a locked prerelease version when preventPrereleaseLock is set to true. Default'You cannot lock your request to a prerelease version. Use a version range instead.'
setByAccept(vndPrefix, verSeparator = '.', suffix = '+json')
- Returns an express middleware that appends a version property to the request object based on accept headers.vndPrefix
- A vendor prefix to use with the accept header.verSeparator
- Optional. The separator to use between the vendor prefix and version.suffix
- Optional. The accept header suffix. Default '+json'.
setBySemverAccept(supportedVersions, vndPrefix, verSeparator = '.', suffix = '+json', preventPrereleaseLock = false, prereleaseMessage = PRERELEASE_MESSAGE)
- Returns an express middleware that appends a version property to the request object based on accept headers.supportedVersions
- An array of versions that are supported.vndPrefix
- A vendor prefix to use with the accept header.verSeparator
- Optional. The separator to use between the vendor prefix and version.suffix
- Optional. The accept header suffix. Default '+json'.preventPrereleaseLock
- Optional. Set to true if you wish to prevent consumers from locking to a prerelease version. If this is set to true and a locked prerelease is requested the server will respond with a 400. Defaultfalse
prereleaseMessage
- Error message to set if a consumer requests a locked prerelease version when preventPrereleaseLock is set to true. Default'You cannot lock your request to a prerelease version. Use a version range instead.'
validateVersion(supportedVersions = [], message = 'Unsupported version requested.')
- Validate that the request version is present and supported.supportedVersions
- An array of versions that are supported.message
- Optional. A message to set for the error.