Lorsqu’un CRM alimente un ERP, qu’une boutique envoie des commandes à la logistique ou qu’une application interne publie des événements pour d’autres systèmes, l’intégration dépend de bien plus qu’une URL, une file d’attente ou un fichier partagé. Elle dépend du fait que toutes les parties interprètent les données de la même manière au fil du temps. Les contrats de données pour les intégrations transforment cette attente en règles explicites, vérifiables et gouvernables.
Leur objectif n’est pas de documenter une interface une seule fois, mais d’éviter qu’un changement apparemment mineur — renommer un champ, autoriser un nouvel état ou modifier une unité monétaire — ne provoque des erreurs silencieuses, des retraitements ou des décisions métier erronées. Ils sont particulièrement utiles lorsque différentes équipes, des applications tierces et des déploiements suivant des calendriers indépendants sont impliqués.
Qu’est-ce qu’un contrat de données et quel problème résout-il ?
Un contrat de données définit l’accord opérationnel entre le producteur d’informations et son consommateur. Il s’applique à une réponse de service, un événement, un fichier périodique, une table partagée ou un message dans une file d’attente. Il décrit ce qui est fourni, ce que cela signifie, dans quelles conditions c’est valide et comment cela évoluera.
Par exemple, un message de commande contenant orderId, status et amount doit préciser si le montant est exprimé en unités ou en centimes, quelle devise s’applique, quels états sont admis, si une commande annulée peut avoir un montant de zéro et si un même message peut arriver plusieurs fois. Sans ces règles, deux systèmes peuvent techniquement accepter le même JSON tout en agissant de manière incompatible.
Le contrat réduit trois risques fréquents :
- Ruptures directes : un consommateur ne peut pas désérialiser, valider ou traiter une donnée modifiée.
- Erreurs sémantiques : le format semble correct, mais la signification d’un champ ou d’une règle métier change.
- Dépendances invisibles : un producteur ignore qu’un champ, une valeur ou un comportement est utilisé par d’autres consommateurs.
Documentation, schéma et contrat opérationnel
La documentation explique comment une intégration devrait fonctionner. Un schéma formalise une partie de cette explication : structure, noms, types, champs obligatoires et, selon la technologie, contraintes. Les deux sont nécessaires, mais ne suffisent pas à exploiter une intégration de manière sûre.
Le contrat opérationnel associe le schéma à des décisions pouvant être révisées et testées : propriétaire, consommateurs connus, politique de compatibilité, gestion des versions, règles sémantiques, niveau de qualité minimal, traitement des erreurs et procédure de changement. Il peut être représenté avec OpenAPI, AsyncAPI, JSON Schema, Avro, Protobuf, SQL ou une autre spécification, mais l’outil ne remplace pas ces décisions.
Un contrat utile devrait inclure au minimum :
- Identité et périmètre : nom, objectif, canal, producteur, responsable et classification de sensibilité.
- Structure : champs, types, cardinalité, caractère obligatoire, formats et exemples valides.
- Sémantique : signification, unité, fuseau horaire, devise, catalogue de valeurs et règles de calcul.
- Qualité : unicité, plages de valeurs, relations entre champs, fraîcheur attendue et ordre lorsque cela est pertinent.
- Exploitation : fréquence, limites de taille, ordre de livraison, tentatives de reprise, conservation et canal de signalement des incidents.
- Évolution : version, changements compatibles, changements nécessitant une coordination et période de retrait.
Compatibilité : évaluer les changements selon une perspective explicite
La terminologie de la compatibilité peut varier d’une équipe à l’autre. Afin d’éviter les décisions erronées, il est conseillé d’adopter la perspective habituelle de lecture des schémas, utilisée par de nombreux registres de schémas : la compatibilité rétroactive, ou vers l’arrière, signifie que le nouveau schéma ou consommateur peut lire des données produites avec le schéma précédent ; la compatibilité prospective, ou vers l’avant, signifie que l’ancien schéma ou consommateur peut lire des données produites avec le nouveau schéma. La compatibilité totale exige les deux directions.
Cette définition ne permet pas de déduire le comportement réel en examinant uniquement une règle abstraite. Elle doit être vérifiée avec le format, le sérialiseur, le schéma de lecture et l’implémentation concrète du consommateur. Ajouter un champ facultatif avec une valeur par défaut, par exemple, peut être compatible vers l’arrière si la nouvelle version sait compléter son absence lors de la lecture de données anciennes. Mais un ancien consommateur ne pourra lire le nouveau message que si sa technologie et son implémentation ignorent les champs inconnus ou si son schéma de lecture résout correctement ce champ au moyen d’une valeur par défaut. Cela ne doit pas être présumé sans test.
Avant d’approuver un changement, posez des questions concrètes : la nouvelle version peut-elle traiter des messages déjà stockés ? L’ancienne version peut-elle continuer à traiter les messages émis durant un déploiement progressif ? Qu’en est-il des consommateurs externes qui ne se mettent pas à jour au même rythme ? La réponse doit provenir de tests représentatifs, et non uniquement de l’étiquette de compatibilité du registre.
En règle pratique, l’ajout de champs réellement facultatifs, l’extension de métadonnées non interprétées ou la correction de descriptions sont généralement des changements moins risqués. La suppression ou le renommage de champs, la modification de types, le resserrement de plages de valeurs, l’altération d’unités, la réinterprétation des valeurs nulles ou l’introduction de valeurs d’énumération qui activent une logique différente nécessitent généralement une nouvelle version et une coordination. Conserver temporairement un champ obsolète et publier une date de retrait offre une transition plus sûre que sa suppression immédiate.
Conception selon le type d’échange
Un même principe prend des formes différentes selon le mécanisme. Pour les événements, identifiez le fait survenu, l’instant métier, l’origine, l’identifiant de l’événement et l’entité concernée. Indiquez si l’événement est immuable, s’il peut arriver dans le désordre et s’il existe des événements de correction.
Si la livraison est effectuée au moins une fois, le consommateur a besoin d’une stratégie vérifiable pour détecter ou tolérer les doublons. Il peut utiliser un identifiant d’événement enregistré dans un registre de déduplication, une clé métier avec des opérations idempotentes, une contrainte de stockage ou un mécanisme équivalent convenu. Une clé d’idempotence est une option fréquente, mais pas une exigence universelle. L’essentiel est de définir quels doublons sont attendus, pendant combien de temps ils sont détectés et quel résultat leur retraitement doit produire.
Dans les réponses synchrones de services, le contrat doit distinguer les données métier, les erreurs fonctionnelles et les défaillances techniques. Il est préférable de définir les codes, la structure des erreurs, les champs sûrs pour le diagnostic et les conditions de reprise. Pour les chargements périodiques, précisez la date de coupure, le fuseau horaire, si le fichier contient une charge utile complète ou incrémentielle, la clé de rapprochement et le comportement en présence d’enregistrements répétés ou absents.
Tests de contrat avant et après la mise en production
Les tests de contrat automatisent la vérification que le producteur et le consommateur respectent l’accord. En développement, validez des exemples valides et non valides par rapport au schéma et aux règles sémantiques pertinentes. Incluez les cas limites : valeurs nulles autorisées, valeurs inconnues, décimales, dates avec fuseau horaire et combinaisons de champs dépendants.
En intégration continue, le changement de contrat doit être comparé à la dernière version publiée. Le contrôle peut bloquer les modifications incompatibles, exiger une nouvelle version ou nécessiter l’approbation du responsable. Il est également conseillé d’exécuter des consommateurs de référence ou des tests convenus avec les consommateurs critiques sur des données de test produites par la nouvelle version.
Avant la mise en production, testez la coexistence entre les versions qui existera réellement pendant le déploiement. Après la publication, observez les taux d’échec de validation, les messages envoyés en quarantaine, les erreurs de désérialisation, les retards de traitement et la proportion de valeurs inconnues. Enregistrez les identifiants techniques, la version du contrat, le type d’erreur et l’origine ; évitez d’inclure des données personnelles, des secrets ou des charges utiles complètes lorsqu’ils ne sont pas indispensables au diagnostic.
Gouvernance du changement, exceptions et traçabilité
Un flux léger et explicite évite que le contrat ne devienne un document oublié. Le producteur propose le changement avec sa motivation, l’impact prévu, un exemple avant et après, la classification de compatibilité et le plan de retrait. Les responsables des consommateurs concernés examinent la sémantique et les tests. Un propriétaire désigné approuve, publie la version et communique la fenêtre d’adoption.
Les exceptions doivent également être définies. Si une valeur hors plage arrive, il n’est pas toujours nécessaire de rejeter l’intégralité de la charge : elle peut être envoyée en quarantaine, marquée pour examen ou acceptée avec un indicateur de qualité, selon le risque métier. Pour les valeurs inconnues d’un catalogue, déterminez si le consommateur doit les ignorer, les préserver, appliquer un comportement sûr ou arrêter le processus. Distinguez soigneusement un champ absent, un champ null et une valeur vide : ils peuvent exprimer des situations différentes.
Enfin, conservez un registre versionné des contrats, des décisions de compatibilité, des approbations, des dates de dépréciation et des preuves de test. Cette traçabilité permet de répondre à la question de savoir qui a changé quoi, pourquoi cela a été considéré comme sûr et quels consommateurs devaient s’adapter. Ainsi, l’évolution ne dépend plus de vérifications manuelles et devient une discipline technique vérifiable.