Over a million developers have joined DZone.

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 Future of Enterprise Integration: Learn how organizations are re-architecting their integration strategy with data-driven app integration for true digital transformation.

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.

Make your mark on the industry’s leading annual report. Fill out the State of API Integration 2019 Survey and receive $25 to the Cloud Elements store.

google ,semantic ,versioning ,strategies ,apis

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}