Gestion des versions

L'API Ad Manager propose à la fois des versions majeures nommées et des versions sur place rétrocompatibles avec la version majeure actuelle.

Les services, les méthodes et les champs peuvent être marqués comme obsolètes à tout moment dans une version majeure (par exemple, v1). Toutefois, ils resteront compatibles jusqu'à ce que cette version majeure soit abandonnée.

Versions majeures

Une version majeure est définie comme une version comportant des modifications d'API incompatibles avec les versions antérieures. Ces versions seront nommées et auront des points de terminaison d'API différents. Les versions majeures précédentes sont compatibles pendant une période de migration.

L'API Ad Manager ne dispose pas d'une cadence de publication régulière pour les versions majeures. Les nouvelles versions majeures ne seront publiées que lorsque cela sera nécessaire.

Versions sur place

Les modifications rétrocompatibles, y compris les nouvelles fonctionnalités et les corrections de bugs, sont publiées sur place dans la version majeure actuelle de l'API. Les clients doivent gérer les champs inconnus dans les réponses de l'API.

Rétrocompatibilité

La rétrocompatibilité est maintenue pour les modifications apportées dans une version majeure. La compatibilité est définie comme suit :

  1. Compatibilité avec la source : le code écrit pour une version précédente est compilé pour une version plus récente et s'exécute correctement avec une version plus récente de la bibliothèque cliente.

  2. Compatibilité en communication : le code écrit pour une version précédente communique correctement avec un serveur plus récent. En d'autres termes, non seulement les entrées et les sorties sont compatibles, mais les attentes en matière de sérialisation et de désérialisation continuent de correspondre.

  3. Compatibilité sémantique : le code écrit pour une version précédente continue de recevoir ce que la plupart des développeurs raisonnables attendraient.

Les tableaux suivants énumèrent les types de modifications d'API et indiquent s'ils sont considérés comme rétrocompatibles.

Services

Type de modification Rétrocompatible
Ajouter un service Oui
Supprimer un service Non

Méthodes

Type de modification Rétrocompatible
Ajouter une méthode Oui
Supprimer une méthode Non
Modifier le type de requête ou de réponse d'une méthode Non

Objets

Type de modification Rétrocompatible
Ajouter un champ obligatoire Non
Ajouter un champ facultatif Oui
Déplacer un champ dans ou hors d'un sous-message Non
Passer un champ du mode "obligatoire" au mode "facultatif" Oui
Passer un champ du mode "facultatif" au mode "obligatoire" Non
Supprimer une restriction immuable Oui
Ajouter une restriction immuable Non

Énumérations

Type de modification Rétrocompatible
Ajouter une valeur enum Oui
Supprimer une valeur enum Non

Comportement des champs obsolètes

Champs de remplacement

Pour les champs qui ont un remplacement, les deux champs seront renseignés lorsque cela sera possible. Lors de la mise à jour, vous pouvez définir l'un ou l'autre des champs. Si vous incluez les deux champs dans une requête de mise à jour, vous obtenez une erreur INVALID_ARGUMENT.

Prenons l'exemple du schéma suivant :

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

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

Une réponse en lecture renseigne les deux champs avec des valeurs équivalentes :

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

Les requêtes de mise à jour peuvent définir l'une ou l'autre des valeurs. Si vous incluez les deux champs, vous obtenez une erreur INVALID_ARGUMENT :

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

Les deux 

// 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."
          }
        ]
      }
    ]
  }
}

Fonctionnalités abandonnées

Si une fonctionnalité de produit est abandonnée, les champs correspondants seront marqués comme obsolètes et pourront renvoyer une valeur par défaut sémantiquement appropriée. Les mises à jour peuvent être ignorées.

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