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, v25.0 (or v25) is a major
version, while v25.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, v25):
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,
v25.1).
When a minor version is released, the existing major version endpoint
(https://googleads.googleapis.com/vX) is automatically updated in place. You
don't need to change the version path in your endpoint URLs, and existing code
continues to work without breaking.
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
Periodically, older Google Ads API versions are deprecated and later sunset:
- Deprecated: When a major version (such as
v25) is released, all earlier major versions are marked deprecated. API calls to deprecated versions continue to succeed until their sunset date, and existing client library releases continue to support them, though subsequent client library releases omit deprecated API versions to reduce package size. - 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.