Norwegian Puffin Movies

    This package has been deprecated

    Author message:

    The router has been superseeded by <versioned-api-router>

    express-version-router

    0.5.4 • Public • Published

    express-version-router

    npm version Build Status Coverage Status Dependency Status

    A router for express that manages api versioning.

    Features

    • Parse version from param, path, header, cookie or your own implementation
    • Match version using numbers, regular expression or semver format
    • Configure your own parameters or headers
    • Respond to requests with the matched version in a custom header

    Installation

    npm install --save express-version-router

    Examples

    Set up express with the router:

    var express = require('express');
    var app = express();
    
    var versionRouter = require('express-version-router');
    var router = versionRouter();
    var errorHandler = (req, res) => res.status(404).end('not found');
    app.use(router, errorHandler);        // will only call the errorHandler if it can't resolve the version
    

    Set an endpoint to handle a specific version (version 1 in this case):

    router.get('/myendpoint', 1, (req, res) => res.end('success'));
    
    // curl http://myserver/v1/test => 200 success
    // curl http://myserver/test?v=1 => 200 success
    // curl -H "X-ApiVersion: 1" http://myserver/test => 200 success
    // curl http://myserver/test => 404 not found
    

    Set an endpoint to handle a version based on semver:

    router.get('/myendpoint', /^2/, (req, res) => res.end('success'));
    
    // curl http://myserver/v2/test => 200 success
    // curl http://myserver/v2.1/test => 200 success
    // curl http://myserver/v2.1.6/test => 200 success
    // curl http://myserver/v3/test => 404 not found
    

    Set an endpoint to handle a version based on a regular expression:

    router.get('/myendpoint', /(3|4)/, (req, res) => res.end('success'));
    
    // curl http://myserver/v3/test => 200 success
    // curl http://myserver/v4/test => 200 success
    // curl http://myserver/v5/test => 404 not found
    

    Set an endpoint to accept multiple version using an array:

    router.get('/myendpoint', [1, '^2', /(3|4)/], (req, res) => res.end('success'));
    
    // curl http://myserver/v1/test => 200 success
    // curl http://myserver/v2/test => 200 success
    // curl http://myserver/v3/test => 200 success
    // curl http://myserver/v4/test => 200 success
    

    API

    Router

    var versionRouter = require('express-version-router');
    var router = versionRouter({
        param: 'v',
        header: 'X-ApiVersion',
        responseHeader: 'X-ApiVersion',
        passVersion: false
    });
    

    The router extends the standard express router and allows for all setting the the standard router has to be used. In addition the router has options specifically for the version mapping:

    • param: the parameter name that is used in query and parameter mapping
    • header: the header used to look for a requested version
    • paramOrder: the order in which parameters are parsed from the client object for all endpoints, the default order is 'params', 'query', 'cookie', 'body', 'header' which map to express properties.
    • responseHeader: the name of the header in the response that has information about the matched version. (will be turned off if this is set to falsy)
    • passVersion: whether to pass the version on via the request object. this will add two new properties to the request object: incomingVersion and acceptedVersion.

    Router.all / Router.METHOD

    router.all(path, [version], [callback, ...] callback)
    router.METHOD(path, [callback, ...] callback)
    

    This method works the same way that the standard express router work, with the addition of an optional version parameter. Any string, number or regular expression is treated as a version that limits what requests this handler will respond to.

    The path supports all the same options that the standard router does, only caveat is that regular expressions prevent the use of path parameters which are disabled in that case (parameter and header methods are still supported though). Instead you can make use of the regular expression subset that express has built in using strings.

    The version can be either an array or a single instance of either:
    A number - will match that number exactly
    A string - will perform semver matching
    A regular expression - will match the incoming version against it

    Callbacks can be any handlers that are compatible with standard express handlers and as usual you can set multiple handlers that will process a request in order. Handlers will receive a req object that now has two additional fields:
    req.incomingVersion - The version that came in on the request req.acceptedVersion - The version that the handler has been configured to accept

    Router.route

    router.route(path)
    

    This is the same as the original method. Note that versioning is not supported at this time for the param call.

    Router.use

    router.use([path], [function, ...] function)
    

    This is the same as the original method. Note that versioning is not supported at this time for the param call.

    Router.param

    router.param(name, callback)
    

    This is the same as the original method. Note that versioning is not supported at this time for the param call.

    Install

    npm i express-version-router

    DownloadsWeekly Downloads

    3

    Version

    0.5.4

    License

    Apache-2.0

    Last publish

    Collaborators

    • mallocator