Node.js module provides versioning for expressjs routes/api

Usage no npm install needed!

<script type="module">
  import expressRoutesVersioning from '';


Express routes versioning

Build Status Coverage Status npm version

Simple node.js module provides versioning for expressjs routes/api.


npm install express-routes-versioning


Follows semver versioning format. Supports '^, ~' symbols for matching version numbers.

    var app = require('express')();
    var routesVersioning = require('express-routes-versioning')();

    app.get('/test', routesVersioning({
       "1.0.0": respondV1,
       "~2.2.1": respondV2

    // curl -s -H 'accept-version: 1.0.0' localhost:3000/test
    // version 1.0.0 or 1.0 or 1 !
    function respondV1(req, res, next) {
       res.status(200).send('ok v1');

    //curl -s -H 'accept-version: 2.2.0' localhost:3000/test
    //Anything from 2.2.0 to 2.2.9
    function respondV2(req, res, next) {
       res.status(200).send('ok v2');

Supporting '^,~' on server might appear as an anti-pattern considering how npm versioning works, where client controls the version. Here server controls the version (or it may not), and client fully trust the server. Typically the client and server belong to the same organization in these cases.


routesVersioning(Options, NoMatchFoundCallback)

Options - object, containing version in semver format (supports ^,~ symbols) as key and function callback (connect middleware format) to invoke when the request matches the version as value. Note: Versions are expected to be mutually exclusive, as order of execution of the version couldn't be determined.

NoMatchFoundCallback (optional)- called if request version doesn't match the version provided in the options. If this callback is not provided latest version callback is called.

How version is determined for each request ?

Default behaviour is to use accept-version headers from the client.

This can be overridden by using a middleware and providing version in req.version property.

How versions are matched ?

semver versioning format is used to match version if versions are provided in semver format, supports ^,~ symbols on the server, else direct mapping is used (for versions like 1, 1.1)


Examples are available here


npm test