When I was recently tasked with designing and building a new set of public-facing REST APIs for a popular online platform, one of the design challenges I faced was whether we should version our web APIs, and if so, how?

Historically there has been a lack of consensus in the industry on best practice in this area of web API design. And on initially researching the problem area I couldn’t find the answers I was looking for, or advice that I felt I could rely on.

This post distills the things I learned from further research and the experience of designing our own web APIs, with the aim of helping those of you that need to tackle a similar design problem. It covers:

• Reasons to consider versioning your web APIs.
• The aspects of a RESTful web API which do and don’t require versioning.
• A classification of the most popular API versioning solutions that are in use today, including which aspect(s) of a RESTful web API they aim to version;
• Points to consider when choosing a versioning solution(s).

It concludes by explaining my current thinking on the best approach to versioning and what solution we adopted for our APIs. I hope you find it useful!
Continue reading →