Cet article décrit les stratégies de gestion des versions utilisées par les API Google. En général, ces stratégies s'appliquent à tous les services gérés par Google.
Il est parfois nécessaire d'effectuer des modifications non compatibles (ou "destructives") avec les anciennes versions de l'API. Ces types de modifications peuvent entraîner des problèmes ou bloquer le code dépendant des fonctionnalités d'origine.
Afin d'éviter les modifications destructives, les API Google utilisent un système de gestion des versions. En outre, les API Google proposent des fonctionnalités uniquement disponibles avec certains niveaux de stabilité, telles que les composants alpha et bêta.
Conseils
Toutes les interfaces d'API Google doivent fournir un numéro de version majeure qui est encodé à la fin du package protobuf et inclus dans la première partie du chemin d'URI des API REST. Si une API intègre une modification destructive, telle que la suppression ou le changement du nom d'un champ, elle doit incrémenter son numéro de version afin d'éviter un blocage soudain du code utilisateur existant.
Une nouvelle version majeure d'API ne doit pas dépendre d'une version majeure précédente de la même API. Une API peut dépendre d'autres API, dans la mesure où l'appelant comprend le risque de dépendance et de stabilité associé à ces API. Dans ce scénario, une version d'API stable ne doit dépendre que des versions stables des autres API.
Les différentes versions d'une même API doivent pouvoir fonctionner simultanément dans une seule application cliente pendant une période de transition raisonnable. Cette période permet au client de passer facilement à la version la plus récente. Une ancienne version doit passer par une période d'abandon raisonnable et bien communiquée avant d'être arrêtée.
Pour les versions présentant une stabilité alpha ou bêta, les API doivent ajouter le niveau de stabilité après le numéro de version majeure dans le package protobuf et le chemin d'URI à l'aide de l'une des stratégies suivantes :
- Gestion des versions stables (recommandé)
- Gestion des versions déployées
- Gestion des versions visibles
Gestion des versions stables
Une version stable est une version de longue durée d'un niveau de stabilité donné, qui reçoit des mises à jour directes. Il n'existe pas plus d'une version par niveau de stabilité pour une version majeure. Dans le cadre de cette stratégie, trois versions sont disponibles : alpha, bêta et stable.
Le niveau de stabilité des versions alpha et bêta doit être ajouté à la version, mais pas à la version stable.
Par exemple, v1 est une version acceptable pour une version stable, contrairement à v1beta ou v1alpha. De même, v1beta ou v1alpha sont des versions acceptables pour les versions bêta et alpha respectives. En revanche, v1 ne l'est pour aucune des deux. Chacune de ces versions reçoit de nouvelles fonctionnalités et des mises à jour "directes".
Les fonctionnalités d'une version bêta doivent être un sur-ensemble des fonctionnalités de la version stable. Les fonctionnalités de la version alpha doivent être un sur-ensemble des fonctionnalités de la version bêta.
Abandonner des fonctionnalités d'API
Les éléments d'API (champs, messages, RPC) peuvent être marqués comme obsolètes dans n'importe quelle version pour indiquer qu'ils ne doivent plus être utilisés :
// Represents a scroll. Books are preferred over scrolls.
message Scroll {
option deprecated = true;
// ...
}
Les fonctionnalités d'API obsolètes ne doivent pas passer de la version alpha à la version bêta, ni de la version bêta à la version stable. En d'autres termes, elles ne doivent pas être "obsolètes" dans l'une des versions.
Les fonctionnalités de la version bêta peuvent être supprimées après avoir été abandonnées pendant une période suffisamment longue, nous recommandons 180 jours. Pour les fonctionnalités qui existent uniquement dans les versions alpha, l'abandon est facultatif. Les fonctionnalités peuvent donc être supprimées sans préavis. Si les fonctionnalités sont obsolètes dans la version alpha d'une API avant leur suppression, l'API doit appliquer la même annotation et peut utiliser n'importe quelle période.
Gestion des versions déployées
Une version individuelle est une version alpha ou bêta qui doit être déployée pendant une période limitée avant que ses fonctionnalités ne soient intégrées à la version stable, après quoi la version individuelle sera arrêtée. Lorsque vous utilisez une stratégie de gestion des versions déployées, une API peut avoir un nombre illimité de versions individuelles à chaque niveau de stabilité.
Le niveau de stabilité des versions alpha et bêta doit être ajouté à la version, suivi d'un numéro de version incrémentiel. Par exemple, v1beta1 ou v1alpha5. Les API doivent préciser l'ordre chronologique de ces versions dans leur documentation (dans les commentaires, par exemple).
Chaque version alpha ou bêta peut être directement mise à jour avec des modifications compatibles avec les versions antérieures. Pour les versions bêta, les mises à jour incompatibles avec les versions antérieures doivent être effectuées en incrémentant le numéro de version et en publiant une nouvelle version avec cette modification.
Par exemple, si la version actuelle est v1beta1, la prochaine version à publier est v1beta2.
Les versions alpha et bêta doivent être arrêtées une fois que leurs fonctionnalités ont été intégrées à la version stable. Une version alpha peut être désactivée à tout moment, alors qu'une version bêta doit accorder aux utilisateurs une période de transition raisonnable, nous recommandons 180 jours.
Gestion des versions visibles
La visibilité des API est une fonctionnalité avancée fournie par l'infrastructure des API Google. Elle permet aux producteurs d'API d'exposer plusieurs vues d'API externes à partir d'une surface d'API interne, et chaque vue est associée à un libellé de visibilité d'API, par exemple :
import "google/api/visibility.proto";
message Resource {
string name = 1;
// Preview. Do not use this feature for production.
string display_name = 2
[(google.api.field_visibility).restriction = "PREVIEW"];
}
Un libellé de visibilité est une chaîne sensible à la casse qui peut être utilisée pour ajouter des tags à tout élément de l'API. Par convention, les libellés de visibilité doivent toujours utiliser des MAJUSCULES.
Un libellé PUBLIC implicite est appliqué à tous les éléments de l'API, sauf si un libellé de visibilité explicite est appliqué comme dans l'exemple ci-dessus.
Chaque libellé de visibilité est une liste d'autorisation. Les producteurs d'API doivent accorder des libellés de visibilité aux utilisateurs d'API pour qu'ils puissent utiliser les fonctionnalités d'API associées aux libellés. En d'autres termes, un libellé de visibilité d'API ressemble à une version d'API avec liste de contrôle d'accès (LCA).
Plusieurs libellés de visibilité peuvent être appliqués à un élément à l'aide d'une chaîne séparée par des virgules (par exemple, "PREVIEW,TRUSTED_TESTER"). Lorsque plusieurs libellés de visibilité sont utilisés, le client n'a besoin que d'un des libellés de visibilité (OR logique).
Une requête API ne peut utiliser qu'un seul libellé de visibilité. Par défaut, le libellé de visibilité attribué à l'utilisateur de l'API est utilisé. Un client peut envoyer des requêtes avec un libellé de visibilité explicite comme suit :
GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW
Les producteurs d'API peuvent utiliser la visibilité des API pour la gestion des versions d'API, comme INTERNAL et PREVIEW. Une nouvelle fonctionnalité d'API commence par le libellé INTERNAL, puis passe au libellé PREVIEW. Lorsque la fonctionnalité est stable et accessible à tous, tous les libellés de visibilité d'API sont supprimés de la définition de l'API.
En général, la visibilité des API est plus facile à mettre en œuvre que la gestion des versions d'API pour les modifications incrémentielles, mais elle dépend de la prise en charge d'une infrastructure d'API sophistiquée. Les API Google Cloud utilisent souvent la visibilité des API pour les fonctionnalités bêta.