Description
This npm package provides an ExpressJS middleware to load route controllers based on api versions. Implementing API Versioning in 15 lines of code.
express-version-route alternatives and similar modules
Based on the "Web Frameworks" category.
Alternatively, view express-version-route alternatives based on common mentions on social networks and blogs.
-
Express
Fast, unopinionated, minimalist web framework for node. -
Nest
A progressive Node.js framework for building efficient, scalable, and enterprise-grade server-side applications with TypeScript/JavaScript ๐ -
Nuxt.js
Nuxt is an intuitive and extendable way to create type-safe, performant and production-grade full-stack web apps and websites with Vue 3. [Moved to: https://github.com/nuxt/nuxt] -
Koa
Expressive middleware for node.js using ES2017 async functions -
egg
๐ฅ Born to build better enterprise frameworks and apps with Node.js & Koa -
verdaccio
๐ฆ๐ A lightweight Node.js private proxy registry -
AdonisJs Framework
AdonisJS is a TypeScript-first web framework for building web apps and API servers. It comes with support for testing, modern tooling, an ecosystem of official packages, and more. -
TypeGraphQL
Create GraphQL schema and resolvers with TypeScript, using classes and decorators! -
Quick Start
๐ A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. ๐ -
MERN
โ๏ธ DEPRECATED - Boilerplate for getting started with MERN stack -
Moleculer
:rocket: Progressive microservices framework for Node.js -
LoopBack
LoopBack makes it easy to build modern API applications that require complex integrations. -
ThinkJS
Use full ES2015+ features to develop Node.js applications, Support TypeScript. -
Derby
MVC framework making it easy to write realtime, collaborative applications that run in both Node.js and browsers -
ActionHero
Actionhero is a realtime multi-transport nodejs API Server with integrated cluster capabilities and delayed tasks -
NestJS REST API boilerplate
NestJS boilerplate. Auth, TypeORM, Mongoose, Postgres, MongoDB, Mailing, I18N, Docker. -
tinyhttp
๐ฆ 0-legacy, tiny & fast web framework as a replacement of Express -
Lad
Node.js framework made by a former @expressjs TC and @koajs team member. Built for @forwardemail, @spamscanner, @breejs, @cabinjs, and @lassjs. -
Marble.js
Marble.js - functional reactive Node.js framework for building server-side applications, based on TypeScript and RxJS. -
sqs-consumer
Build Amazon Simple Queue Service (SQS) based applications without the boilerplate -
FoalTS
Full-featured Node.js framework, with no complexity. ๐ Simple and easy to use, TypeScript-based and well-documented. -
Trails
:evergreen_tree: Modern Web Application Framework for Node.js. -
modern-errors
Handle errors in a simple, stable, consistent way -
lychee.js
:seedling: Next-Gen AI-Assisted Isomorphic Application Engine for Embedded, Console, Mobile, Server and Desktop -
Hemera
๐ฌ Writing reliable & fault-tolerant microservices in Node.js https://hemerajs.github.io/hemera/ -
Catberry
Catberry is an isomorphic framework for building universal front-end apps using components, Flux architecture and progressive rendering. -
Interfake
:computer: Fake APIs for prototypes & automated tests. -
dawson-cli
A serverless web framework for Node.js on AWS (CloudFormation, CloudFront, API Gateway, Lambda) -
AdonisJs Application
This repo is the pre-configured project structure to be used for creating ambitious web servers using AdonisJs. -
sqs-producer
Simple scaffolding for applications that produce SQS messages -
Perk
A well documented set of tools for building node web applications. -
Zeronode
Zeronode - minimal building block for NodeJS microservices -
Restberry
Framework for setting up RESTful JSON APIs with NodeJS. -
QueryQL
Easily add filtering, sorting, and pagination to your Node.js REST API through your old friend: the query string! -
FortJs
A feature-rich Node.js web framework designed for building powerful, scalable, and maintainable web applications. -
Prim+RPC
Easy-to-understand, type-safe, transport-agnostic RPC/IPC for JavaScript, supporting callbacks, batching, file handling, custom serialization, and more. -
khalis
Grab Blogger & Google Photos, mp4upload.com,cloudvideo.tv, etc streaming link
SurveyJS - Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest.
Do you think we are missing an alternative of express-version-route or a related project?
README
express-version-route
This npm package provides an Express middleware to load route controllers based on api versions.
Implementing API Versioning as simple as:
[](.github/express-version-route.png)
now any request would be handled with the appropriate route handler in accordance to request.version
.
Usage
Create a map where the key is the version of the supported controller, and the value is a regular Express route function signature.
const versionRouter = require('express-version-route')
const routesMap = new Map()
routesMap.set('1.0', (req, res, next) => {
return res.status(200).json({'message': 'hello to you version 1.0'})
})
Then, on the route which you wish to version, call the route
function of this module with the map you created:
router.get('/test', versionRouter.route(routesMap))
If no route matches the version requested by a client then the next middleware in the chain will be called. To set a route fallback incase no version matches set a 'default' key on the routes map, for example:
routesMap.set('default', (req, res, next) => {
return res.status(200).json({'message': 'hello to you, this is the default route'})
})
If maximal possible version (for example to get the latest bugfix) is necessary, then please specify useMaxVersion: true
in route
function, then the maximal possible version will be returned for your request. For example for 1.0
request, the version 1.0.2
will be returned:
const routesMap = new Map()
routesMap.set('1.0.0', (req, res, next) => {
return res.status(200).json({'message': 'hello to you version 1.0.0'})
})
routesMap.set('1.0.2', (req, res, next) => {
return res.status(200).json({'message': 'hello to you version 1.0.2'})
})
router.get('/test', versionRouter.route(routesMap,{useMaxVersion: true}))
Usage with TypeScript
import * as versionRouter from 'express-version-route'
import { Router, Handler } from 'express';
const router = Router();
const routesMap = new Map<string, Handler>();
routesMap.set('1.0', (req, res, next) => {
return res.status(200).json({'message': 'hello to you version 1.0'})
})
routesMap.set('default', (req, res, next) => {
return res.status(200).json({'message': 'hello to you, this is the default route'})
})
router.get('/test', versionRouter.route(routesMap))
How it works
The Library
A requested version from the client must be available on the request object at req.version
.
You are encouraged to use this module's twin: express-version-request which is another simple Express middleware that populates req.version
from the client's X-Api-Version header, Accept header or from a query string (such as 'api-version=1.0.0')
The key for the routes versions you define can be a non-semver format, for example: 1.0
or just 1
. Under the hood, expression-version-route
uses the semver
module to check if the version found on the request object at req.version
matches the route.
Client-Server flow
An API client will send a request to your API endpoint with an HTTP header that specifies the requested version of the API to use:
curl --header "X-Api-Version: 1.0.0" https://www.example.com/api/users
The
express-version-request
library will parse theX-Api-Version
and sets Express'sreq.version
property to 1.0.0.The
express-version-route
library, when implemented like the usage example above will match the 1.0 route version because semver will match 1.0.0 to 1.0, and then reply with the JSON payload{'message': 'hello to you version 1.0'}
.
Installation
yarn add express-version-route
TypeScript Support
yarn add --dev @types/express-version-route
Note: Don't forget to add types for Express as well!
Tests
yarn test
Project linting:
yarn lint
Coverage
yarn test:coverage
Commit
The project uses the commitizen tool for standardizing changelog style commit messages so you should follow it as so:
git add . # add files to staging
yarn commit # use the wizard for the commit message
On API Versioning...
An API versioning is a practice that enables services to evolve their APIs with new changes, signatures and the overall API contract without interrupting API consumers and forcing them to repeatedly make changes in order to keep in pace with changes to APIs.
Several methodologies exist to version your API:
- URL: A request specifies the version for the resource:
http://api.domain.com/api/v1/schools/3/students
- Query String: A request specifies the resource in a query string:
http://api.domain.com/api/schools/3/students?api-version=1
- Custom HTTP Header: A request to a resource
http://api.domain.com/api/schools/3/students
with a custom HTTP header set in the requestX-Api-Version: 1
- MIME Type content negotiation: A request to a resource
http://api.domain.com/api/schools/3/students
with anAccept
header that specifies the requested content and its version:Accept: application/vnd.ecma.app-v2+json
There is no strict rule on which methodology to follow and each has their own pros and cons. The RESTful approach is the semantic mime-type content negotiation, but a more pragmatic solution is the URL or custom HTTP header.
Why API Versioning at all ?
Upgrading APIs with some breaking change would lead to breaking existing products, services or even your own frontend web application which is dependent on your API contract. By implementing API versioning you can ensure that changes you make to your underlying API endpoints are not affecting systems that consume them, and using a new version of an API is an opt-in on the consumer. read more...
Alternative Node.js libraries
Several npm projects exist which provide similar API versioning capabilities to Express projects, and I have even contributed Pull Requests to some of them that provide fixes or extra functionality but unfortunately they all seem to be unmaintained, or buggy.
- https://github.com/Prasanna-sr/express-routes-versioning
- https://github.com/elliotttf/express-versioned-routes
- https://github.com/biowink/express-route-versioning
Author
Liran Tal [email protected]