Versioning

Objective: Learn how Google Ads API versioning works.

Semantic versioning

The Google Ads API follows semantic versioning where there is a a major and a minor version. The format of the version is MAJOR.MINOR or vMAJOR_MINOR. For example, v5_0 is a major version, while v5_1 is a minor version.

See the release notes for past versions.

Major versions

Major release versions introduce some breaking, backwards incompatible changes. The version would end in zero with the format vX_0 where X is the major version number.

Each major version has a separate endpoint. This is an example of the URL where X is the major version number.

https://googleads.googleapis.com/vX

If you are upgrading from an older major version, then your code may require changes when you switch to the new major version endpoint. If you are using our client libraries, then upgrade to the newest version. When there is a major version released, we will provide a migration guide that you should go through to fix 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 from 0 to -- as default value.
• Changing the error reason returned from A to B.

Minor versions

Minor versions only introduce backwards compatible changes. For a minor version, vMAJOR_MINOR would have a MINOR number greater than zero.

When a minor version is released, the endpoint that is already in use will automatically be updated. This will not cause your code to break. You can continue to use your existing client libraries.

Minor versions include new features or updates that do not affect your existing code. If you want to use these new features, then upgrade your client libraries to the newest version.

Sunsets

Periodically, older Google Ads API versions will need to sunset. We will post notices on the developer blog when a version is about to sunset. The deprecation schedule is updated with future sunset dates.