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
,
}
