Versionnage d’API : Spécification
Versionnage HTTP public avec des changements uniquement additives à l’intérieur d’une version, règles explicites pour les changements incompatibles, en-têtes Sunset avant suppression, et une politique documentée de version par défaut qui ne redéfinit jamais silencieusement la signification d’un champ.
Statut du package : contexte de référence prêt pour revue humaine. Le contrat et les scénarios de test sont complets, mais aucune garantie n’est donnée qu’une implémentation adoptante les ait validés.
Décision
Les API HTTP publiques identifient un contrat servi par un nom de version explicite. À l’intérieur d’une version nommée, seuls les changements additives sont autorisés : champs de réponse optionnels, nouveaux points de terminaison, et nouveaux membres d’énumération que les anciens clients peuvent ignorer. Modifier la signification, le type, la nullabilité ou l’unité d’un champ existant est un changement incompatible et nécessite un nouveau nom de version, une entrée dans le journal des modifications, et une suite de contrats consommateurs. Les clients qui omettent l’en-tête de version reçoivent la version la plus ancienne encore supportée, jamais la plus récente. Les versions Sunset continuent de servir leur contrat figé et annoncent les en-têtes Sunset et Deprecation jusqu’à leur suppression.
Portée
- Ressources REST publiques listées comme public-apis dans le profil d’adoption.
- Sélection de version, politique par défaut, classification additive versus incompatible, signalement de Sunset, et rejet des versions inconnues.
Hors de ce cadre
- Évolution des payloads d’événements sur bus de messages (package event-schema associé).
- Fonctionnement des suites consommateurs et fournisseurs en CI (package contract-testing associé).
Contrat
- Une requête nomme une version servie ou, si l’en-tête est omis, exécute la version la plus ancienne supportée et renvoie ce nom dans la réponse.
- Un nom de version inconnu ou retiré échoue fermement avec un code documenté et ne bascule pas vers un autre schéma.
- Les changements additives ne modifient jamais les types, unités, codes d’erreur existants, ni la signification de null versus absent.
- Les changements incompatibles ne peuvent pas être déployés sous un nom de version existant ; ils nécessitent une nouvelle version servie et un fonctionnement en double jusqu’au Sunset de l’ancien nom.
- Les versions Sunset incluent les en-têtes Sunset et Deprecation dans chaque réponse pour cette version jusqu’à l’instant de Sunset.
- Les noms de champs retirés dans une nouvelle version restent lisibles sous l’ancienne version avec l’ancienne signification jusqu’à la suppression de cette version.
Guide d’implémentation
- Représenter la version comme un choix de sérialiseur, pas par des branches dispersées dans les handlers. Générer des schémas fournisseur par version et échouer en CI lorsqu’une différence sur une version existante est classée incompatible.
- Les caches doivent varier selon l’en-tête de version.
Gestion des erreurs et sécurités
- La réinterprétation silencieuse d’un champ sous le même nom est un défaut. Si les sérialiseurs ne sont pas d’accord sur une version, échouer la requête plutôt que de mélanger deux schémas.
- Après l’instant de Sunset, cette version retourne l’échec version-inconnue.
Vérification et exploitation
- Les tests de contrat fixent des réponses golden par version servie et rejettent les différences inattendues de signification de champ. Les métriques canary comptent le trafic version-inconnue et Sunset avant suppression.
Les exemples à l’apparence exécutable dans ce package sont des fixtures et contrats d’acceptation. Lancez
python tools/validate.py depuis la racine de la collection pour vérifier la structure et les métadonnées du package ; puis
implémentez et exécutez les scénarios dans le dépôt cible.
Hypothèses d’adoption
- Les noms et valeurs numériques dans
example.yamlsont un profil d’adoption, pas des valeurs par défaut universelles. - L’équipe adoptante doit mapper acteurs, classes de données, vocabulaire d’erreur, et propriété à son système.