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:

https://gist.github.com/jamsesso/cc60d0d0fd920b2810c6

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 API.

Show your support

Clapping shows how much you appreciated Sam Jesso’s story.