Stratégies pour le générateur d’API de données
Un ensemble de stratégies régit le générateur d’API de données en lien avec les changements cassants, les notifications, les mises en production et le contrôle de version.
Contrôle de version et versions
Une version dans le contexte du générateur d’API de données fait référence à chaque version publiée du logiciel, identifiée par le Major.Minor.Patch format. Ces versions se répartissent en trois catégories : stable, changement cassant et préversion.
Versions stables
Une version stable du générateur d’API de données est à compatibilité descendante. La compatibilité descendante implique que tout code que vous écrivez qui s’appuie sur une version d’un générateur d’API de données peut adopter une version stable plus récente sans nécessiter de modifications de code pour maintenir l’exactitude ou les fonctionnalités existantes.
Versions de modifications cassants
Une version de modification cassant du générateur d’API de données n’est pas rétrocompatible. L’adoption d’une version de modification cassante dans le code client existant peut nécessiter des modifications du code pour s’assurer que le client se comporte exactement comme il l’a fait lors du ciblage de la version précédente.
Les versions des modifications cassants sont annoncées via l’article de liste des changements cassants et dans la description des modifications d’une version GitHub. La publication d’une préversion/version release candidate précède les versions modifiées cassants, sauf si les modifications corrigent des problèmes de sécurité, de confidentialité ou juridiques critiques. Même si les versions précédentes du générateur d’API de données peuvent rester disponibles sur la page des versions de GitHub, nous vous recommandons d’effectuer une mise à niveau vers la dernière version, qui peut inclure des correctifs de bogues.
Versions précommerciales
Les versions préliminaires du Générateur d’API de données sont identifiées avec le schéma de X.Y.Z-rc contrôle de version. Le -rc suffixe indique que la build est un « release candidate ». Les préversions sont utilisées pour recueillir des commentaires sur les nouvelles fonctionnalités et d’autres modifications.
Sauf si nous prévoyons d’apporter des modifications significatives à partir de la dernière version stable, nous publions la préversion suivante avec tout ce qui est issu de la dernière version stable et des nouvelles fonctionnalités de préversion. La prochaine mise à jour du générateur d’API de données peut interrompre certaines des nouvelles fonctionnalités de préversion que nous avons ajoutées entre les versions préliminaires. Ce comportement cassant signifie que vous devrez peut-être modifier votre code pour que les choses fonctionnent à nouveau.
Les versions d’évaluation ne sont pas destinées à une utilisation à long terme ou en production. Lorsqu’une nouvelle version stable ou en préversion devient disponible, il est possible que les anciennes versions d’évaluation ne soient plus accessibles. Il est préférable d’utiliser des versions préliminaires uniquement lorsque vous travaillez activement sur de nouvelles fonctionnalités et que vous êtes prêt à passer à une version non préversion peu après la publication. Si certaines fonctionnalités d’une préversion sont incluses dans une nouvelle version stable, les fonctionnalités d’évaluation restantes sont ajoutées à une nouvelle préversion pour vous permettre de l’essayer.
Table des modifications de version
Important
Nous pouvons introduire une modification cassant d’une version mineure ou corrective lorsque la modification résout des bogues de produit critiques, des problèmes juridiques, de sécurité ou de confidentialité.
| Type de version | Version précédente | Nouvelle version | Notes |
|---|---|---|---|
| Modification avec rupture | 1.Y.Z |
2.Y.Z |
Nouvelles fonctionnalités et correctifs de bogues, ainsi que toutes les modifications cassants. |
| Stable | 1.1.Z |
1.2.Z |
Nouvelles fonctionnalités et correctifs de bogues sans modification cassant, sauf si les modifications répondent aux bogues critiques du produit, aux problèmes juridiques, de sécurité ou de confidentialité. |
| Stable | 1.1.1 |
1.1.2 |
Correctifs de bogues sans nouvelles fonctionnalités ou changements cassants, sauf si les modifications corrigent les bogues critiques du produit, les problèmes juridiques, de sécurité ou de confidentialité. |
| Préversion | X.Y.1-rc |
X.Y.2-rc |
Nouvelles fonctionnalités en préversion et correctifs de bogues. (Les modifications cassants sont incluses si la version principale est bousculée.) |
Changements cassants
Pour hiérarchiser la sécurité, améliorer les fonctionnalités et maintenir la qualité du code, les nouvelles versions de nos logiciels peuvent inclure des modifications cassants. Bien que nous nous efforçons de minimiser ces changements en faisant des choix architecturaux minutieux, ils peuvent toujours se produire. Dans de tels cas, nous faisons une priorité de les annoncer et de fournir des solutions possibles.
Important
Nous pouvons apporter des modifications sans préavis si la modification est considérée comme sans rupture, ou s’il s’agit d’une modification cassant apportée pour résoudre des bogues critiques du produit ou des problèmes juridiques, de sécurité ou de confidentialité.
Qu’est-ce qu’un changement cassant ?
Une modification cassant est une modification qui vous oblige à mettre à jour votre application pour éviter les interruptions. Dans le générateur d’API de données, les modifications cassants peuvent inclure des modifications des contrats d’API REST, GraphQL génération de schémas et d’autres éléments qui affectent la compatibilité et les fonctionnalités.
Exemples de changements cassants
Les exemples suivants sont une liste non exhaustive de modifications cassants apportées au générateur d’API de données :
- Modifications du contrat d’API REST
- Modifications dans GraphQL génération de schéma
- Modifications affectant la compatibilité descendante
- Suppression ou renommage d’API ou de paramètres
- Modifications apportées aux codes d’erreur
- Ajustements de la fonctionnalité de définition d’autorisation
- Suppression des paramètres autorisés, des champs de requête ou des champs de réponse
- Ajout de paramètres obligatoires ou de champs de requête sans valeurs par défaut
- Modifications apportées à la fonctionnalité de point de terminaison d’API prévue
Définition d’une modification non cassante
Une modification sans rupture fait référence à une modification qui peut être intégrée à votre application sans provoquer d’interruption. Les modifications non cassantes sont généralement communiquées après l’implémentation. Votre application doit être conçue pour gérer ces modifications sans préavis.
Exemples de modifications non cassants
Les exemples suivants sont une liste non exhaustive de modifications non insécables apportées au générateur d’API de données :
- Introduction de nouveaux points de terminaison
- Ajout de méthodes aux points de terminaison existants
- Incorporation de nouveaux champs dans les réponses et les demandes
- Ajustements de l’ordre de champ dans les réponses
- Introduction des en-têtes de requête facultatifs
- Modifications apportées à la longueur des données et à la taille de la réponse
- Modifications apportées aux messages d’erreur et aux codes
- Correctifs aux codes de réponse HTTP
- Métadonnées supplémentaires dans les documents OpenAPI générés
Comment communiquer les changements cassants ?
Nous faisons en sorte qu’il soit prioritaire de vous informer rapidement des changements cassants. Vous trouverez des notifications de modifications cassants dans les notes de publication des versions du générateur d’API de données sur GitHub et dans l’article dédié à la liste des modifications cassants.
Liste des changements cassants actuels
Des changements cassants et des retraits de fonctionnalités sont annoncés dans cet article.
- À l’heure actuelle, il n’y a pas de changements cassants