npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

express-request-version

v2.2.0

Published

Request versioning middleware for express.

Downloads

377

Readme

Express Request Version

Greenkeeper badge

Build Status Coverage Status

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. Default false
    • 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. Default false
    • 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.