Versioning your API is terrifying. If you push out a “breaking change” – basically any change that runs counter to what client developers have planned for, such as renaming or deleting a parameter or changing the format of the response – you run the risk of bringing down many, if not all, of your customers’ systems, leading to angry support calls or – worse – massive churn. For this reason, versioning is the number one concern among the development teams I work with when helping them design their APIs.
The traditional way of handling versioning in REST is to apply some version number to the URL – either in the domain (i.e. apiv1.example.com/resource) or in the resource path (api.example.com/v1/resource). Non-breaking changes are frequently pushed out without much fanfare aside from a changelog posted to a blog or an update to the documentation. Breaking changes, on the other hand, require excessive testing, customer hand-holding, voluminous communication and a high level of planning, code maintenance and creative routing as you bend over backwards to ensure your customers can continue to work smoothly while you delicately push out a new release. With all that, everything can still go wrong.
Most API producers handle these issues by placing tight restrictions on their development teams regarding when and how the API may be updated, leading to convoluted policies that often confuse client developers and confound innovation and iteration. For example, Facebook recently described their new versioning strategy for their Marketing API. In the old days, Facebook was rather cavalier about pushing out breaking changes. “Move fast and break things” worked fine for them, but annoyed the developers who relied on their API. Though they have apparently learned their lesson, their solution to versioning – which, to be fair, is common among RESTful API providers – prevents their API from taking advantage of continous releases and forces their client developers to assiduously watch for announcements about new releases.
There’s a better way.