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.
- NodeJs v16.15.1
- NPM v8.11.0
- 2022-10-05 Change the RouteTo function to be the last middleware in the stack.
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));
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
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
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.
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
Rafael Chavez Solis rafaelchavezsolis@gmail.com
MIT License (MIT) - LICENSE file for details