Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Guidance on Versioning Your API From Google

DZone's Guide to

Guidance on Versioning Your API From Google

Knowing when and how to version your API to reflect changes and inform your users in a complex art. Google has API versioning down to a fine art form.

· Integration Zone
Free Resource

The Integration Zone is brought to you in partnership with Cloud Elements.  What’s below the surface of an API integration? Download The Definitive Guide to API Integrations to start building an API strategy.

I always enjoy learning about how companies are versioning their APIs. The topic is always one of the most discussed areas when we do APIStrat workshops, and is an aspect of the API space where I think there is never a 100% right way of doing things — making it an area where I recommend learning as many different approaches as you can, then deciding on the right solution for your particular situation.

To help you in your journey (and mine), I try to document any official versioning strategies published by the API providers I research. Today, I have one from Google, providing some very interesting insight into how they version their APIs. Google uses semantic versioning, which follows this approach to each version number MAJOR.MINOR.PATCH, incrementing the:

  • MAJOR version when you make incompatible API changes.
  • MINOR version when you add functionality in a backwards-compatible manner.
  • PATCH version when you make backwards-compatible bug fixes.

When it comes to their REST APIs, Google puts the version in URL. I'm still learning more about their approach to how it's applied to the proto package for gRPC APIs. They also have some good advice when it comes to what breaking is and non-breaking changes.

Backwards-compatible (non-breaking) changes:

  • Adding an API interface to an API service definition.
  • Adding a method to an API interface.
  • Adding an HTTP binding to a method.
  • Adding a field to a request message.
  • Adding a field to a response message.
  • Adding a value to an enum.
  • Adding an output-only resource field.

Backwards-incompatible (breaking) changes:

  • Removing or renaming a service, field, method or enum value.
  • Changing an HTTP binding.
  • Changing the type of a field.
  • Changing a resource name format.
  • Changing the visible behavior of existing requests.
  • Changing the URL format in the HTTP definition.
  • Adding a read/write field to a resource message.

This Google API versioning advice comes from their API design guide. I also found some versioning advice from them as part of the Google Cloud Endpoints documentation, which provides some easier to follow advice for REST APIs. It also includes some advice for handling as part of your OpenAPI definition, something I will be investigating further.

I am just looking to add semantic versioning approach, the example of putting the version in the URL, and the advice on backwards-compatibility to my API research. It helps me keep my work full of healthy examples and URL references to how specific API providers are documenting their own APIs — as well as offering guidance to customers who are using their services to design, deploy, and manage their APIs.

The State of API Integration Report provides data from the Cloud Elements platform and will help all developers navigate the recent explosion of APIs and the implications of API integrations to work more efficiently in 2017 and beyond.

Topics:
google ,semantic ,versioning ,strategies ,apis

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}