Alex MacCaw from Clearbit has written a nice overview about approaches for API versioning. Today we want to elaborate how we deal with API versioning at Babbel.
From the three wide-spread options (using the URL, using a request header, using a dynamic date), we have chosen to go for using URLs. This is the most straightforward solution with minimal overhead for clients.
In addition to a major version, we opted to use a Semantic Versioning approach.
Example:
https://api.babbel.com/v4.1.0/en/learn_languagesMajor version
The major version specifies general requirements and constraints for all endpoints belonging to this version. For example:
- request/response content types (JSON, XML, …)
- usage of application specific HTTP header fields
- path schema (/:locale/:resource/:uuid)
- general structure of request/response body (serialization rules)
- general usage of HTTP status codes
Minor version
The minor version is increased every time a breaking change to any of the endpoints is made. Breaking changes could be:
- changes of a resource serialization (removing attributes or associations)
- removing a resource
- changing the behavior of a resource
Tiny version
The tiny version can be used to indicate non-breaking changes to the API such as:
- addition of attributes in the serialization of resources
- addition of resources
Once a minor version of the API is changed, all existing API endpoints are migrated to the new version even if there is only a change for one of many resources.
As an attentive reader you will have noticed that this is not 100% according to Semantic Versioning, as our minor versions allow breaking changes on a resource level.
It is a compromise we knowingly made. The reason is that for our architecture we had to ensure that major version changes are limited to larger changes on how APIs are built. E.g. introducing a different way of authentication, moving towards a different serialization approach, etc. Changes on the resource level, such as removing deprecated resources and attributes, should not lead to major version updates. Hence, such changes are reflected by minor version updates.
This approach to API versioning is part of the Babbel API Standards that have been established by a Community of Practice at Babbel. Semantic API versioning allows us to roll out new features and perform maintainance work safely without breaking any client.
Photo by Suzanne D. Williams on Unsplash