Versioning

  • The Ad Manager API utilizes Major version releases for backward-incompatible changes and in-place releases for backward-compatible updates within a Major version.

  • Deprecated services, methods, and fields will remain functional until the Major version they belong to is retired, although breaking changes might occur during the Beta phase.

  • Backward compatibility within a Major version is ensured for source, wire, and semantic compatibility to minimize disruptions for existing integrations.

  • While adding new services, methods, and optional fields is backward compatible, removing or significantly altering existing elements is generally not, requiring careful consideration during upgrades.

  • Deprecated fields might have replacements, and in such cases, either the original or the replacement field can be used, but using both simultaneously will result in an error.

The Ad Manager API has both named Major version releases and backward compatible in-place releases to the current Major version.

Services, methods, and fields could be marked as deprecated at any time within a Major version (e.g. v1), however, they will remain supported until that Major version is retired.

Major version releases

A Major version release is defined as a release with backward incompatible API changes. These releases will be named and have different API endpoints. Previous Major versions are supported for a migration period.

The Ad Manager API does not have a regular release cadence for Major versions. New Major versions will only be released when necessary.

In-place releases

Backward compatible changes including new features and bug fixes are released in-place to the current Major API version. Clients must handle unknown fields in API responses.

Backward Compatibility

Backward compatibility is maintained for changes within a Major version. Compatibility is defined as:

  1. Source compatibility: Code written against a previous release compiles against a newer release, and successfully runs with a newer version of the client library.

  2. Wire compatibility: Code written against a previous release communicates correctly with a newer server. In other words, not only are inputs and outputs compatible, but the serialization and deserialization expectations continue to match.

  3. Semantic compatibility: Code written against a previous version continues to receive what most reasonable developers would expect.

The following tables enumerate types of API changes and if they are considered backward compatible.

Services

Type of Change Backward compatible
Add a new service Yes
Remove a service No

Methods

Type of Change Backward compatible
Add a new method Yes
Remove a method No
Change a method's request or response type No

Objects

Type of Change Backward compatible
Add a required field No
Add an optional field Yes
Moving a field into or out of a submessage No
Change a field from required to optional Yes
Change a field from optional to required No
Remove an immutable restriction Yes
Add an immutable restriction No

Enumerations

Type of Change Backward compatible
Add an enum value Yes
Remove an enum value No

Deprecated field behavior

Replacement fields

For fields that have a replacement, both fields will be populated when feasible. When updating, either field can be set. Including both fields in an update request results in an INVALID_ARGUMENT error.

Consider the following schema:

{
  // The cost of this Foo in micros.
  // Deprecated: Use `cost` instead.
  "costMicros": number,

  // The cost of this Foo.
  "cost": {
    object (Money)
  }
}

A read response populates both fields with equivalent values:

{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  }
}

Update requests can set either value. Including both fields results in an INVALID_ARGUMENT error:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

cost 

// Update payload
{
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

Both 

// Update payload
{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "costMicros",
            "description": "Cannot update both costMicros and cost."
          }
        ]
      }
    ]
  }
}

Discontinued features

If a product feature is discontinued, corresponding fields will be marked as deprecated and may return a semantically appropriate default value. Updates can be ignored.

{
  // The salesperson split amount in micros.
  // Deprecated: The Sales Management feature has been deprecated. This field
  // will always be `0`.
  "salespersonSplitMicros": number,
}