AI-generated Key Takeaways
- 
          The Ad Manager API uses both named Major version releases and backward compatible in-place releases. 
- 
          Services, methods, and fields can be marked as deprecated but remain supported until the Major version is retired. 
- 
          Major version releases involve backward incompatible changes and have different API endpoints. 
- 
          Backward compatible changes, including new features and bug fixes, are released in-place to the current Major API version. 
- 
          Backward compatibility within a Major version is defined by source, wire, and semantic compatibility. 
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:
- Source compatibility: Code written against a previous release compiles against a newer release, and successfully runs with a newer version of the client library. 
- 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. 
- 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,
}