Easy-Version

Comprehensive middleware for API versioning

Middlweare for Express framework to enable API versioning. Implements versioning through content media fields (content-negotiation) to specify the version as media type for ensure backwards compatibility using request headers.

The goal of this middleware is to avoid the URI versioning, replacing by the use of common request headers.

E.g.

Accept: application/wm.my-service-name+json;version=2.0.0

Content-Type: application/wm.my-service-name+json;version=2.0.0

The recommended format for the media type is:

application/<prefix>.<service-name>+json;version=<version>

• Its strongly suggest that specify the version value using semantic versioning (https://semver.org/).
• The prefix value is optional, but is recommended to use the prefix to avoid conflicts with other media types. E.g. ms for Microservice, wm for web-middleware, etc.
• The service-name value is the name of the service (API) that is being versioned.

References

• RFC 9110 paper

Build with

• NodeJs v16.15.1
• NPM v8.11.0

Last Update

• 2022-10-05 Change the RouteTo function to be the last middleware in the stack.

Get Started

For use this package, first install as dependency

npm i easy-version

Import into the express application

const {
    registerVersion,
    routeTo
} = require('easy-version');

Register middlerware for detects the requested API version

    app.use(registerVersion());

For each route, regiter the handlers per accepted version of the API

const pathVersions = {
    "1.0.0": Controller.myCustomHandler,
    "2.0.0": myCustomHandlerV2,
};
app.get('/path', routeTo(pathVersions));

Response Headers

Its recommended that the APIs must send a Vary header to enable cache and proxies to differentiate between versions (as below):

res.setHeader("Content-Type", "application/x.service-name+json;version="+req.version);
res.setHeader("Vary", "Content-Type");

This headers will be injected automatically

Documentation

registerVersion (customParser)

Function to parse the Accept header value for get the version requested and registers it to the request version attribute.

@param {function} customParser (Optional) Function to execute a custom parse logic for detects the version

routeTo (args, notVersionFound)

Function to execute the correct handler for the version requested.

@param {object} args (Required) Map with the version number and its handler

@param {function} notVersionFound (Optional) Default callback for executes if no version found

Note: This function is responsible for call the request handlers, so its necessary that the handlers are registered before this function and returns a response. No middleware can be registered after this function.

Request.version

Injects the version detected into the version attribute of the standard request object. So its available to read in all the requests.

req.version Attribute to get the received version

Author

Rafael Chavez Solis [e-mail]

License

MIT License (MIT) - LICENSE file for details