Google, Azure and Stripe all use API versioning to manage changes to an API contract as clients evolve, but they do not follow one shared versioning standard. Google documents major versions in URL paths; Azure API Management lets an API owner choose among paths, headers and query parameters; Stripe uses its own major and monthly release model. Their common goal is to make change understandable and give clients control over when to adopt it.
How the three approaches compare
| Provider and scope | Where versioning appears | How changes are handled | Client adoption |
|---|---|---|---|
| Google’s published API principles; minor/major workflow specifically in Cloud Endpoints | Google’s general principles put the major version in the URL path. Cloud Endpoints documents major and minor versions. | In Cloud Endpoints, use a minor version for backward-compatible additions and a major version when a change breaks client code. | Clients can move to a major version when ready; the Google sources explain the versioning principles and the Cloud Endpoints workflow, not one universal migration mechanism for every Google API. |
| Azure API Management | The API owner can place the version identifier in the URL path, an HTTP header or a query parameter. Versions of a logical API can be grouped in a version set. | Versions are typically used for breaking changes; revisions are available for minor, nonbreaking changes. | Clients select a version using the configured identifier. This describes Azure API Management, not every Azure service. |
| Stripe | Stripe documents named API releases, rather than prescribing a general URL-path, header or query-parameter scheme. | Stripe distinguishes potentially backward-incompatible major releases from backward-compatible monthly releases. | Stripe recommends testing a new API version before upgrading. Its release labels and cadence are Stripe-specific. |
What API versioning is meant to solve
An API is a contract: it defines what requests a client can make and what responses it can rely on. If a provider changes that contract, existing integrations may need code changes. Versioning gives the provider a way to introduce changes while allowing clients to identify the contract they are using and manage when they move to another one.
As an Amazon Associate I earn from qualifying purchases.
That shared purpose does not make the mechanisms interchangeable. A version in a URL, a header, a query parameter or a provider’s release label has different operational consequences. These examples are provider-specific approaches, not implementations of a single cross-industry versioning standard.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchGoogle: major versions in paths, with a Cloud Endpoints workflow
Google Cloud product manager Dan Ciruli described the general Google approach in a 2017 post: “Our major versions are reflected in the path of our APIs, immediately following the domain.” The post sets out broad principles, not a universal implementation rule for every Google API. Read Google’s explanation of API versioning.
#1 Best Overall
For the more specific mechanics, Google Cloud Endpoints documentation recommends changing the minor version for backward-compatible additions and the major version when a change breaks client code. That guidance applies to Cloud Endpoints; it should not be read as a specification for every Google API. See the Cloud Endpoints API lifecycle guidance.
Azure: API Management versions and revisions are separate concepts
Azure API Management supports three places for a version identifier: the URL path, an HTTP header or a query parameter. It can group versions of a logical API into a version set, which helps organize the versions of that API. The available choices are product-specific; “Azure” covers many services with different API designs. Microsoft explains versioning in Azure API Management.
API Management also distinguishes versions from revisions. Microsoft’s guidance says: “Typically, versions are used to separate API versions that have breaking changes, and revisions can be used for minor and non-breaking changes to an API.” In practical terms, versions address a change that may require clients to adapt; revisions provide a separate mechanism for smaller changes. These terms describe API Management’s model, not a universal distinction imposed on all Azure APIs.
A related but distinct policy applies to services covered by the Azure REST API specifications repository. Its uniform-versioning policy calls for immutability and lockstep alignment of a service’s operations, documentation and SDKs for a given service version. This repository policy should not be generalized into a rule for every Azure API. Read the Azure REST API specifications uniform-versioning policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Stripe: major and monthly releases, with testing before upgrade
Stripe describes major releases as potentially backward-incompatible and monthly releases as backward-compatible. Those categories and the monthly cadence are Stripe’s own release model, not a general rule for other API providers. See Stripe’s API versioning documentation.
Stripe’s documentation advises: “As a precaution, use API versioning to test a new API version before committing to an upgrade.” The useful distinction is between evaluating a new version and making an upgrade that affects an integration. The documentation’s recommendation is specifically about Stripe’s API; the exact testing setup depends on how a client integrates with Stripe.
What they agree on—and what they do not
All three approaches make API change more legible to consumers: clients need a way to understand which contract they depend on and to manage changes that could require code updates. Each provider also distinguishes, in its own way, changes that can be adopted more easily from changes that may disrupt existing clients.
They do not agree on one version-number format, one place to express a version, or one release schedule. Google’s path-based major version principles, Azure API Management’s configurable identifier and version/revision concepts, and Stripe’s release labels solve related problems through different product-specific mechanisms. Choose an approach based on the needs and conventions of the API you own; do not assume one provider’s implementation is a universal requirement.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
