Versioning APIs is difficult, and everyone in the API space has opinions about how to do it properly. It’s also almost impossible to avoid. As teams build new software, occasionally they need to get rid of a feature (or provide that feature in a different way). Versioning gives your API users a reliable way to understand semantic changes in the API. While some companies will go to great lengths to never change a version, we don’t have that luxury: with the number of APIs we operate, the number of teams developing them here and the number of developers relying on them, we version APIs so developers know what to expect from them.
Versioning APIs should be done according to a consistent and comprehensive policy. At Google, we follow the general principles of semantic versioning for our APIs. The principles behind semantic versioning are simple: each release gets a number, X and a number Y. X indicates a major version, and Y indicates a minor version. A new major version indicates a backward-incompatible change while a new minor version indicates a backward-compatible change.
Our major versions are reflected in the path of our APIs, immediately following the domain. Why? Well, it means that any API URL that you call will never rename or drop any of the fields you rely on. If you're doing a GET on
coolcloudapi.googleapis.com/v1/coolthings/12301221312132, you can rely on the fact that the JSON returned will never have fields renamed or removed.There are pros and cons to this approach, of course, and many smart people have heated debates over the “right” way to version. Some people prefer encoding a version request in a header, others “keep track” of the version that any individual API consumer is used to getting. We’ve seen and heard them all, and collectively we’ve decided that, for our broad purposes, encoding the major version in the URL makes the most sense most of the time.
Note that the minor version is not encoded in the URL. That means that if we enhance the Cool Cloud API by adding a new field, you may one day be surprised when a call to
coolcloudapi.googleapis.com/v1/coolthings/12301221312132 starts returning some additional data. But we’ll never "break" your app by removing fields.When we release a new major version, we generally write a single backend that can handle both versions. All requests (regardless of version) are sent to the backend, and it uses the version in the path to decide which surface to return.
For customers using Cloud Endpoints, our API gateway, we’re starting to release the features that will enable you to follow these same versioning practices.
First, our proxy can now serve multiple versions of your API and reports the API version. This will let you see how much traffic different versions of your API receive. In practice, this means that you can tell how much of your traffic has migrated to a new version.
Second, it can give you a strategy for deprecating and turning down an API — by finding out who's still using the old version. But that’s a topic for another blog post for another day.
Versioning is the thorn on the rose of making better APIs. We believe in the approach we’ve adopted internally, and are happy to share the best practices we’ve developed with the community. To get started with Cloud Endpoints, check out our 10-minute-quickstart or in-depth tutorials, or reach out to us on our Google Group at [email protected] — we’d love to hear from you!
