APIs sometimes go through changes that are so big they require a new version to make sure API users don’ t break their apps. Versioning APIs is, however, difficult and some teams go out of their way to avoid it. Google can’ t do that and…
APIs sometimes go thru changes that are so big they require a new version to make sure API users don’ t break their apps. Versioning APIs is, however, difficult and some teams go out of their way to avoid it. Google can’ t do that and so they’ ve developed some simple, consistent rules for versioning APIs. Dan Ciruli over at the Google Cloud Platform, explains how the search giant versions their APIs.
Google follows the principles of semantic versioning. This involves giving each release a number, X and Y. X indicates a major version, which means backward-incompatible changes, while Y indicates a minor version. A minor version means changes backwards-compatible with the last major version.
Google decided to place the major version immediately after the domain in the path of the API endpoints. The reason is that it wanted to make sure users would never have to rename or drop any fields in an API call for it to work. So, if you do a GET on ‘coolcloudapi.googleapis.com/v1/coolthings/12301221312132’ , the JSON will never have fields renamed or removed. Although some developers would suggest putting the API version in the request header, Google decided that putting the major version in the URL makes the best sense in most cases.
Minor versions on the other hand aren’ t encoded in the URL. That means the same call may one day suddenly return JSON with new fields. No worries, though: your app will never break because no fields will ever be removed or renamed.
For its own API gateway, Cloud Endpoints, Google is starting to release features so you can follow the same versioning practices. Its proxy lets you serve multiple versions of the same API and provides reporting on how your users are using different versions. Working out who’s using an old version can then help you form a strategy to phase out deprecated versions.
