README.md

koa-router-version

Semantic Versioning routing for Koa

Allows you to use Semantic Versioning routes.

Requisites:

• Node.js >= 7.6.0
• Koa >= 2.0.0
• Koa Router >= 7.0.0

Installation

npm install --save koa-router-version

# with yarn:
yarn add koa-router-version

Usage

A basic usage:

const Koa = require('koa');
const Router = require('koa-router');
const api = require('koa-router-version');

const list = require('./list');
const detail = require('./detail');
const detail2 = require('./detail2');

const app = new Koa();
const router = new Router();

// Defines a version 1.0.0 for todo list
router.get('todo.list', '/todo', api.version({'1.0.0': list}));

// Defines 2 versions (order is NOT important)
router.get('todo.detail', '/todo/:id', api.version({
    '1.1.0': detail,
    '2.1.3': detail2
}))

// You can specify a route param as version. Will accept both /todo/321 and /v1/todo/321 
router.get('todo.detail', '/:version(v\\d)?/todo/:id', api.version({
    '1.1.0': detail,
    '2.1.3': detail2
}))

app.use(router.routes());

app.listen(3000);

For client usage:

# Latest version
$ curl -i http://localhost:3000/todo/1
HTTP/1.1 200 Accepted
X-Api-Version: 2.1.3
<more headers>

{"todo": {}}

# Specifying a version
$ curl -i -H "Accept-Version: ^1.0" http://localhost:3000/todo/1
HTTP/1.1 200 Accepted
X-Api-Version: 1.1.0
<more headers>

{"todo": {}}

# Specifying a version via path
$ curl -i http://localhost:3000/v1/todo/1
HTTP/1.1 200 Accepted
X-Api-Version: 1.1.0
<more headers>

{"todo": {}}

$ curl -i -H "Accept-Version: ~2" http://localhost:3000/todo/1
HTTP/1.1 200 Accepted
X-Api-Version: 2.1.3
<more headers>

{"todo": {}}

# Path has higher priority than header
$ curl -i -H "Accept-Version: ~2" http://localhost:3000/v1/todo/1
HTTP/1.1 200 Accepted
X-Api-Version: 1.1.0
<more headers>

{"todo": {}}

# Unknown version
$ curl -H "Accept-Version: ^3.0" http://localhost:3000/todo/1
HTTP/1.1 400 Bad Request
<more headers>

Version ^3 is not supported

Version state variable

You can access the used version through the ctx.state:

router.get('todo.list', '/todo', api.version({'1.0.0': ctx => {
  ctx.body = ctx.state.apiVersion;
}));

Options

requestHeader

The default header is Accept-Version, but you can change:

router.get('todo.list', '/todo', api.version(
  {'1.0.0': list},
  { requestHeader: 'X-Request-Version' }
));

responseHeader

The default header is X-Api-Version, but you can change:

router.get('todo.list', '/todo', api.version(
  {'1.0.0': list},
  { responseHeader: 'X-Version' }
));

routeParam

This module expects the path as v followed by a single number:

• v1 is equivalent to ^1
• v2 is equivalent to ^2
• v11 is equivalent to ^11

The default param is version, but you can change it:

router.get('todo.list', '/:myversion(v\\d)/todo', api.version(
  {'1.0.0': list},
  { routeParam: 'myversion' }
));

In order to make version optional and use the latest, use the ? regex at the end:

router.get('todo.list', '/:myversion(v\\d)?/todo', api.version(
  {'1.0.0': list},
  { routeParam: 'myversion' }
));

fallbackLatest

When the requested version is not found, the default response is an error, but you can choose to use the latest version:

router.get('todo.list', '/todo', api.version(
  {'1.0.0': list},
  { fallbackLatest: true }
));

$ curl -i -H "Accept-Version: ^3.1.9" http://localhost:3000/todo/1
HTTP/1.1 200 Accepted
X-Api-Version: 2.1.3
<more headers>

{"todo": {}}