Page Summary
-
The Google Ads API follows semantic versioning with major and minor versions.
-
Major versions introduce breaking changes and have separate endpoints, requiring code updates and migration guides when upgrading.
-
Minor versions are backward-compatible, automatically update the existing endpoint, and include new features without breaking existing code.
-
Older Google Ads API versions are periodically sunset, with notices posted on the developer blog and the deprecation schedule updated.
Semantic versioning
The Google Ads API follows semantic versioning with a major and
a minor version number. Versions are written as MAJOR.MINOR or vMAJOR.MINOR.
For example, v26.0 (or v26) is a major
version, while v26.1 is a minor version.
See the release notes for details on current and past versions.
Major versions
Major release versions introduce breaking, backward-incompatible changes. The
initial release of a major version ends in zero (vX.0, or vX, where X is
the major version number).
Each major version has a separate REST and gRPC endpoint path (vX), which does
not include the minor version suffix. In the following URL, X is the major
version number (for example, v26):
https://googleads.googleapis.com/vX
If you are upgrading from an older major version, your code may require changes when you switch to the new major version endpoint. If you are using our client libraries, upgrade to the client library release that supports the new major version. When a major version is released, we provide an upgrade guide to help you resolve any breaking changes in your code.
Examples of breaking changes include:
- Removing or renaming a service, interface, field, method, or enum value.
- Changing the type of a field.
- Changing a resource name format.
- Changing the URL format in the HTTP definition.
- Changing output formats, such as changing default values.
- Changing the error reason returned from A to B.
Minor versions
Minor versions introduce only backward-compatible changes. For a minor version,
vMAJOR.MINOR has a MINOR number greater than zero (for example,
v26.1).
When a minor version is released, the existing major version endpoint
(https://googleads.googleapis.com/vX) is automatically updated in place. All
API calls to a specific major version always go to the latest corresponding
minor version, and the Google Ads API doesn't support calling specific minor versions.
You don't need to change the version path in your endpoint URLs, and existing
code continues to work without breaking. The lifespan of minor versions isn't
tracked separately. Instead, minor versions share the same sunset date as their
corresponding major version.
Minor versions add features or updates that don't affect your existing code. To use fields or features from a minor version with a client library, upgrade your client library to a release that includes the minor version definitions.
Deprecation and sunsets
The Google Ads API maintains multiple active major versions at any time. Periodically, earlier versions are deprecated and later sunset:
- Deprecated: A version is considered deprecated only if it is explicitly marked as deprecated. API calls to deprecated versions continue to succeed until their sunset date.
- Sunset: A version is disabled on its sunset date, and all API calls to its endpoint fail.
We post announcements on the developer blog in advance of version sunsets. Check the deprecation and sunset schedule for active, deprecated, and scheduled sunset dates.