Versioning REST API routes in Express.js

Over the past few months I have been building a RESTful web service that is to be consumed from both the web as well as an HTML5 hybrid mobile app powered by the Ionic framework. The web consumer doesn’t present much of a problem since the API will only be consumed by a first-party web client. On the other hand, I cannot leave mobile app users dead in the water if they decide against upgrading.

The clear solution to this problem is API versioning. It works as simply as offering different versions of your API to consumers while still allowing you to add new features and (potentially) break stuff in the process.

I have been writing the API in Javascript using Express.js and was looking for a clean and easy way to implement versioning. The method that was inspired by a few hours of reading is to simply have the version specified in the request URI, with the default version being the latest. So, say I have a couple of routes:

• GET /v1/user/:id
• GET /v2/user/:id
• GET /user/:id -> GET /v2/user/:id

Two versions of the API exist (in this example, a REST call for consuming a single user record), version 1 & 2. Since version 2 is the latest version, any call to the default API version (latest) is simply redirected* to the latest implementation of that REST call in my API; in this case, version 2.

Express, being as awesome as it is, is actually very easily configured for this sort of thing. The implementation of the above routes are as follows:

var express = require('express');

var http = require('http');

var app = express();



// Simple user controller implementation.

var users = [

  { username: 'jamsesso', age: 20, gender: 'M' },

  { username: 'bettycrocker', age: 20, gender: 'F' }

];



// Version 1 (Old)

function findUser(req, res) {

  res.json(users[req.params.id]);

}



// Version 2 (New & improved)

function findUser2(req, res) {

  if(!users.hasOwnProperty(req.params.id)) {

    res.send(404);

  }

  else {

    res.json(users[req.params.id]);

  }

}



// Set up the routing.

var v1 = express.Router();

var v2 = express.Router();



v1.use('/user', express.Router()

  .get('/:id', findUser));



v2.use('/user', express.Router()

  .get('/:id', findUser2));



app.use('/v1', v1);

app.use('/v2', v2);

app.use('/', v2); // Set the default version to latest.



// Setup server.

http.createServer(app).listen(8081, function () {

  console.log('Magic is happening on port 8081');

});

With this approach, it is also possible to implement different middleware depending on the API version which is quite a powerful capability — think beta user authentication, etc…

Hopefully this is of some use to any future developers working on an Express.js REST