DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations

Trending

  • What Is Test Pyramid: Getting Started With Test Automation Pyramid
  • A Complete Guide to AWS File Handling and How It Is Revolutionizing Cloud Storage
  • Apache Kafka vs. Message Queue: Trade-Offs, Integration, Migration
  • Working on an Unfamiliar Codebase
  1. DZone
  2. Data Engineering
  3. Databases
  4. Guidance on Versioning Your API From Google

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.

Kin Lane user avatar by
Kin Lane
·
Mar. 15, 17 · Opinion
Like (4)
Save
Tweet
Share
9.13K Views

Join the DZone community and get the full member experience.

Join For Free

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.

API Google (verb)

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

Opinions expressed by DZone contributors are their own.

Trending

  • What Is Test Pyramid: Getting Started With Test Automation Pyramid
  • A Complete Guide to AWS File Handling and How It Is Revolutionizing Cloud Storage
  • Apache Kafka vs. Message Queue: Trade-Offs, Integration, Migration
  • Working on an Unfamiliar Codebase

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: