
Intégration et qualité des données
Versions et dépréciations d’API : organiser une migration maîtrisée
Une intégration peut continuer à répondre tout en changeant de structure ou de sens métier. Inventoriez les versions, surveillez les dépréciations et validez les commandes déjà ouvertes avant de basculer.
Inventorier plusieurs versions à la fois
Stripe explique que la version utilisée dans les appels et celle des événements reçus peuvent relever de paramètres différents. Le changelog Demand décrit des changements par collection et version. Le simple numéro d’un SDK ne constitue donc pas un inventaire complet de votre intégration.
Relevez endpoint, version des requêtes, bibliothèque cliente, schéma des réponses, événements reçus et exports. Associez chaque élément aux opérations métier qui en dépendent : devis, réservation, modification, annulation, remboursement et rapprochement.
Distinguer changement de forme et changement de sens
Un champ supprimé provoque souvent une erreur visible. Une valeur nouvellement possible peut passer silencieusement dans une branche par défaut et dégrader le service. Documentez champs requis, unités monétaires, valeurs d’état et règles de présence. Un montant qui change de base par personne à base par dossier doit être traité comme un changement métier.
Classez les annonces en ajout compatible, dépréciation, rupture de contrat et changement de couverture. Pour chaque annonce pertinente, consignez date de publication, échéance annoncée, source, responsable et décision. Une dépréciation sans échéance connue reste à clarifier auprès du partenaire.
Créer un jeu de preuves avant la migration
Préparez des réponses expurgées de données personnelles et des fixtures de test autorisées. Incluez une vente, un refus, une annulation partielle et un dossier créé avant la bascule. Comparez les valeurs utiles au client et à la comptabilité, pas seulement la réussite HTTP.
| Élément | Preuve à conserver |
|---|---|
| Requête | Version explicitement utilisée et paramètres validés. |
| Réponse | Mapping des champs et états inconnus traités. |
| Événement | Version, déduplication et traitement des retards. |
| Dossier ouvert | Consultation et après-vente encore possibles. |
Éviter les doubles actions pendant la coexistence
Une phase où deux destinations reçoivent le même événement peut doubler les notifications, les écritures ou les traitements financiers. Préparez une règle qui distingue observation et exécution. Reliez les événements à leur identité métier et gardez une seule décision effective.
La comparaison parallèle doit privilégier les lectures et tests autorisés. Ne dupliquez pas une création de réservation réelle pour comparer deux versions. Si la nouvelle version modifie une commande, vérifiez séparément les conditions de retour arrière : le code ancien peut ne plus comprendre l’état nouvellement enregistré.
Borner la bascule et ses conditions d’arrêt
- Faire valider l’inventaire par technique, vente et comptabilité.
- Tester les changements déclarés puis les exceptions du parcours.
- Ouvrir un périmètre réduit et surveiller les dossiers incertains.
- Interrompre l’extension si prix, documents ou états divergent.
- Fermer l’ancienne voie seulement après traitement des dossiers restants.
Le retour arrière doit décrire configuration, données et événements à reprendre. Une simple remise en ligne du code précédent ne restaure pas automatiquement les commandes.
Maintenir un calendrier de suivi exploitable
Attribuez la lecture des changelogs à une personne et une fréquence adaptée aux contrats. Le registre doit indiquer la dernière lecture, les annonces concernées et les actions encore ouvertes. Les équipes d’assistance ont besoin de savoir quelle version a produit le dossier qu’elles prennent en charge.
Reliez la migration au plan de reprise et au support fournisseur. Une échéance technique doit devenir une tâche datée avec une preuve de clôture.
Tester les consommateurs d’un schéma qui change
Scénario fictif : Une version ajoute un état inconnu au logiciel de support. Faites traiter un exemple fictif par chaque consommateur avant la bascule ; la seule réussite du producteur ne démontre pas leur compréhension.
| Point | Preuve | Contrôle proposé |
|---|---|---|
| Contrat à conserver | Version du contrat et options | Faire préciser ce qui est fourni et ce que le traitement peut conclure. |
| Résultat à rapprocher | Réponse de chaque consommateur | Comparer le résultat effectivement observé à celui attendu pour ce cas. |
| Décision de reprise | Les dossiers refusés restent retrouvables pendant la transition. | Attribuer la suite et garder l’inconnue visible tant que la preuve manque. |
Les dossiers refusés restent retrouvables pendant la transition.
Cadre documentaire : JSON Schema : vocabulaire de validation 2020-12 — référence consultée le . Validation structurelle 2020-12 ; aucun résultat de validation d’un catalogue réel ni contrôle des droits de vente.
Approfondir le parcours : OpenAPI 3.1.1 : relier les opérations au contrat du parcours voyage
La veille des versions doit conserver la version de description OpenAPI séparément de celle du produit ou de l’API métier. Une évolution du fichier demande de relire les opérations et leurs consommateurs. Le registre d’écart relie contrat précédent, nouveau contrat et observation autorisée.
OpenAPI 3.1.1 : relier les opérations au contrat du parcours voyage · Rapprocher les preuves du parcours
Approfondir le parcours : Notes de version : changement utile, dossiers concernés et préparation
Une dépréciation doit être expliquée dans les notes utiles aux consommateurs du parcours. Version, échéance et préparation gardent leur source. Le changement annoncé reste distinct de celui effectivement diffusé et vérifié.
Notes de version : changement utile, dossiers concernés et préparation · Rapprocher les preuves du parcours
OpenAPI 3.1.1 : un format déclaré n’est pas toujours une validation
Cette lecture porte sur la version 3.1.1, sans la présenter comme la version la plus récente. Le contrat du fournisseur doit préciser sa propre version et le dialecte pris en charge.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Dialecte | Le Schema Object repose sur JSON Schema Draft 2020-12, avec le dialecte OpenAPI. | Configurer le validateur pour le dialecte annoncé, plutôt que supposer l’équivalence avec un ancien contrat. |
| format | Le dialecte par défaut utilise format comme annotation ; sa présence ne suffit pas à imposer une validation du format. | Vérifier explicitement la validation des dates, adresses et identifiants sensibles. |
| readOnly et writeOnly | Ces annotations portent sur le sens lecture/écriture des champs. | Distinguer les propriétés acceptées dans la requête de celles retournées en réponse. |
Un contrat de données ne démontre pas l’activation commerciale d’une opération ni la qualité du service d’assistance.
OpenAPI Specification 3.1.1 — Schema Object · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Demand API 3.2 : migrer les champs de prix et les filtres
Le guide de migration 3.2 décrit des changements de structure. Une réponse qui reste un JSON valide peut donc nécessiter un nouveau mapping de champs.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Prix affiché | Le guide demande price.display à la place de price.book. | Identifier la version de la réponse avant d’interpréter le champ manquant comme un prix absent. |
| Charges | price.charges remplace extra_charges dans la structure décrite ; les indicateurs included_in.display et chargeable_online distinguent affichage et encaissement. | Ne pas déduire le lieu de paiement du seul classement d’une charge dans le prix affiché. |
| Filtres | Des filtres précédemment placés à la racine sont regroupés sous filters. | Comparer le corps de requête avant et après migration ; une valeur bien nommée au mauvais niveau ne filtre pas nécessairement les résultats. |
Cette correspondance est attachée au guide de migration 3.2. Elle ne doit pas être transposée sans vérification à une autre version ou à tous les endpoints Orders.
Booking.com — migration 3.2, recherche d’hébergements · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Sources et périmètre des faits documentés
La date de consultation figure avec chaque référence. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.
- Stripe : mise à niveau d’une intégration : Version des requêtes, SDK et destinations d’événements. (consultée le )
- Booking.com Demand : archive des changements : Changements par version et par collection ; périmètre à vérifier. (consultée le )
- JSON Schema : vocabulaire de validation 2020-12 : Validation structurelle 2020-12 ; aucun résultat de validation d’un catalogue réel ni contrôle des droits de vente. (consultée le )
- OpenAPI Specification 3.1.1 — Schema Object : Un contrat de données ne démontre pas l’activation commerciale d’une opération ni la qualité du service d’assistance. (consultée le )
- Booking.com — migration 3.2, recherche d’hébergements : Cette correspondance est attachée au guide de migration 3.2. Elle ne doit pas être transposée sans vérification à une autre version ou à tous les endpoints Orders. (consultée le )
Questions fréquentes
Questions utiles avant de décider
Mettre à jour le SDK suffit-il ?
Non. Vérifiez les requêtes, réponses, événements, mappings et opérations sur les dossiers déjà ouverts.
Peut-on comparer deux créations en production ?
Évitez de dupliquer une action réelle. Utilisez des lectures, un mode observation ou un environnement de test autorisé.
Que faire d’une nouvelle valeur d’état ?
La conserver et déclencher un traitement explicite ; ne pas l’assimiler silencieusement à un état connu.
Quand retirer l’ancienne version ?
Après validation des flux nouveaux, des événements et de l’après-vente des dossiers existants, selon les possibilités du partenaire.
Tester les consommateurs d’un schéma qui change : quelle preuve conserver ?
Conservez version du contrat et options, réponse de chaque consommateur et la décision attribuée. Les dossiers refusés restent retrouvables pendant la transition.





