Un fournisseur ralentit, tronque ses réponses ou refuse une partie des appels pendant que les consommateurs continuent d’émettre. Répondre malgré tout avec une donnée ancienne ou incomplète peut provoquer une décision fausse bien après la disparition du timeout initial.
Le contrat de dégradation décrit ce qui reste vrai : fraîcheur maximale, champs garantis, réponse explicite, stockage temporaire et moment de la coupure. Identifiants d’idempotence, journaux corrélés, accusés, files et contrôles fonctionnels préparent la reprise. Schéma, payload, mapping, webhook, retry, rate limit, ERP et CRM sont relus depuis la transaction métier, pas depuis le seul taux de réponses HTTP.
Le bon arbitrage préfère parfois un refus clair à un succès partiel. Le consommateur doit pouvoir distinguer une donnée définitive, une valeur obsolète, une demande mise en attente et une opération non exécutée. Si la fraîcheur dépasse quinze minutes ou si un champ garanti disparaît, alors le contrat renvoie un état dégradé explicite ; en revanche, une réponse complète sous le plafond de latence reste consommable. Le seuil signé ouvre ou ferme ce mode ; le rejeu conserve la même identité et démontre qu’aucun second effet n’a été créé. Cette règle est testée sur un timeout avant effet, un timeout après effet et une réponse tronquée, puis rapprochée dans l’ERP et le CRM avant le retour nominal.
Dawap conçoit ces contrats et les exercices associés dans ses missions d’intégration API sur mesure. Producteur, consommateurs, métier et exploitation partagent alors la promesse réduite, la file à réconcilier et le verdict qui autorise le retour au service nominal.
Définir ce que le consommateur peut encore croire pendant la panne
La promesse critique décrit ce que le consommateur peut encore croire pendant la panne. Elle fixe la fraîcheur maximale d’une donnée, les champs éventuellement absents, les opérations refusées et la manière de reconnaître une réponse dégradée. Sans ce contrat, un code 200 peut transformer une information périmée en décision métier apparemment valide.
Contrat API : choisir ce qui doit survivre à la défaillance
Le producteur documente les réponses possibles ; le métier décide lesquelles restent exploitables ; le consommateur traite explicitement le statut dégradé ; l’exploitation surveille fraîcheur, quotas et files. Les identifiants d’idempotence et la corrélation restent obligatoires, car une réponse réduite ne doit pas rendre le rejeu opaque.
Cas concret : le référentiel répond avec douze heures de retard alors que le consommateur attend un prix applicable immédiatement. Contre-intuitivement, un succès technique dégradé peut être plus dangereux qu’un refus explicite lorsqu’il confirme une donnée incomplète. Le coût caché se lit dans les doublons, les données anciennes, les décisions fausses et la reprise manuelle, pas seulement dans le budget visible. Le contrat de dégradation précise donc réponse, fraîcheur, stockage, seuil de coupure et rejeu avant toute extension du service réduit.
Distinguer les appels à maintenir, différer ou refuser
Les lectures tolérant une donnée ancienne peuvent parfois continuer avec un âge affiché. Les écritures irréversibles attendent ou sont refusées. Les événements rejouables rejoignent une file bornée. Cette classification est faite par opération métier, pas seulement par endpoint, car une même route peut servir une consultation sans risque et une décision financière sensible.
Flux : maintenir, différer ou refuser explicitement
La matrice indique pour chaque opération son délai acceptable, sa clé d’idempotence, son stockage temporaire, son propriétaire et son geste de reprise. Elle évite qu’une équipe mette tout en file par réflexe alors que certains messages perdent leur sens après quelques minutes.
Si le référentiel de prix accuse douze heures de retard, afficher l’ancien prix comme actuel crée un faux succès. Selon le contrat, le canal conserve un prix encore valable avec sa date, bloque l’engagement commercial ou demande une validation. Le choix dépend du risque de marge et de la possibilité de corriger ensuite sans léser le client.
Cartographier les dépendances vitales de la reprise d’intégration
Le flux dépend du fournisseur, mais aussi du DNS, des certificats, des quotas, de la file, du stockage des messages, du service d’identité et du référentiel utilisé pour rapprocher les effets. Une cartographie utile montre quelle défaillance rend le mode dégradé lui-même indisponible.
Cartographier les dépendances qui empêcheraient tout rejeu fiable
Chaque dépendance possède un signal indépendant et une conséquence métier. Une expiration côté fournisseur n’a pas la même portée qu’une saturation de la file locale : dans le premier cas les messages peuvent attendre, dans le second leur acceptation même devient incertaine. La procédure relie donc le symptôme au geste qui protège encore l’idempotence.
Deux alertes méritent une attention particulière : la reprise manuelle devient quotidienne, ou une copie locale est utilisée sans date de fraîcheur. Elles annoncent une dégradation devenue permanente. Le coût se déplace alors vers les rapprochements, les doubles effets et les décisions prises sur des valeurs anciennes.
Concevoir le mode dégradé du flux critique
Le mode dégradé est un contrat observable, pas une exception cachée. La réponse indique sa nature, l’âge de la donnée et les capacités indisponibles. Le consommateur peut alors décider sans confondre une information partielle avec le comportement nominal.
Reprise : réduire le service sans produire de mensonge
Le contrat précise les entrées admises, la sortie retournée, les dépendances encore actives, le seuil de bascule et le repli. Un identifiant de corrélation suit la transaction jusque dans la file. L’expiration du mode dégradé est automatique afin qu’une restauration technique ne laisse pas durablement une réponse appauvrie.
Pour le prix ancien de douze heures, le service peut retourner une réponse explicitement périmée à un écran d’information, mais doit refuser une commande qui engagerait le client sur cette valeur. Cette différence protège la promesse métier sans transformer chaque ralentissement en coupure totale.
Ancrer le rejeu sur la dernière transaction entièrement rapprochée
Le point de reprise est le dernier événement dont le producteur, la file et le consommateur partagent le même verdict. Un simple offset technique ne suffit pas si le métier ne sait pas quelles commandes ou quels prix ont effectivement été appliqués.
Contrat API : savoir depuis quel état reconstruire
Le journal relie l’identifiant métier, la clé d’idempotence, la version du payload, l’accusé du fournisseur et l’effet observé chez le consommateur. Le rejeu commence après le dernier ensemble entièrement rapproché, non après le dernier message simplement envoyé.
Les événements au verdict incomplet sont isolés dans une cohorte. Ils sont comparés au système d’autorité avant toute nouvelle émission. Ce tri réduit le débit initial, mais il empêche un rattrapage rapide de doubler les transactions déjà acceptées.
Contenir la file des échanges à réconcilier
La file différée possède un volume, un âge maximal, une date de péremption métier et une capacité de rejeu. Sans ces quatre dimensions, un backlog apparemment stable peut contenir des décisions qui ne doivent déjà plus être exécutées.
Flux : empêcher la file différée de devenir incontrôlable
Les messages sont séparés par type d’effet et par tolérance au retard. Un changement de prix périmé est abandonné ; une commande payée conserve la priorité ; une synchronisation de catalogue peut attendre. Le seuil de coupure empêche d’accepter davantage d’entrées que le système ne pourra rapprocher dans la fenêtre convenue.
Le rejeu démarre par une cohorte dont les clés d’idempotence et les accusés sont vérifiés. Son débit augmente seulement si les doubles effets restent nuls et si la fraîcheur du stock ne se dégrade pas. Cette rampe protège le fournisseur revenu d’une nouvelle saturation.
Réconcilier les effets après reprise du flux critique
La réconciliation compare les intentions reçues, les messages réellement transmis, les accusés et les effets métier. Elle ne se limite pas au nombre de requêtes réussies, car une réponse perdue peut cacher une opération pourtant exécutée.
Exploitation : détecter doublons, trous et statuts contradictoires
Une table de contrôle relie clé métier, version, horodatage producteur, état de file, réponse fournisseur et résultat consommateur. Les doublons, trous et contradictions sont traités séparément. Une correction manuelle porte le même identifiant de corrélation afin de rester visible lors du prochain rapprochement.
La reprise quotidienne à la main et la copie locale devenue référence sont deux signaux d’échec. Elles indiquent que la dégradation n’est plus temporaire. Le flux doit alors être réduit davantage ou corrigé structurellement avant toute extension.
Dire ce qui reste certain sans masquer les données différées
Le message adressé aux consommateurs indique la capacité disponible, la fraîcheur garantie, les opérations refusées et la prochaine réévaluation. Il évite le mot « rétabli » tant que la file différée et les effets métier ne sont pas réconciliés.
Reprise : adapter le message à la certitude disponible
Le producteur publie un statut technique et un statut métier distincts. Le premier décrit latence, quotas et erreurs ; le second précise la portée sur les transactions. Cette séparation permet au support d’expliquer pourquoi l’API répond tout en refusant encore certaines opérations.
Dans le scénario du prix vieux de douze heures, la communication nomme les produits concernés, l’heure de référence et le comportement du canal. Elle ne promet pas un retour complet avant que le rapprochement confirme les prix effectivement utilisés.
Arrêter la reprise avant les doubles effets
Un seuil d’arrêt associe une mesure à une action. La hausse des doubles effets coupe le rejeu ; une fraîcheur dépassée bloque les écritures ; une file dont l’âge maximal progresse réduit le débit entrant. Sans geste automatique ou décideur nommé, le seuil reste décoratif.
Contrat API : savoir quand réduire encore ou interrompre
Les seuils sont évalués par cohorte et par type d’opération. Une moyenne globale pourrait masquer un taux de rejet élevé sur les seules commandes à forte valeur. Le métier signe les limites de fraîcheur ; l’exploitation signe la capacité de file et de rejeu ; le propriétaire du flux tranche l’arrêt.
Après un arrêt, les messages restent conservés avec leur cause et leur version. La reprise ne redémarre qu’après un test fonctionnel sur quelques transactions et la vérification de leurs effets dans le système d’autorité.
Exercer régulièrement la continuité du flux critique
L’exercice simule successivement latence, réponse partielle, quota réduit et accusé perdu. Ces pannes n’appellent pas le même geste ; les regrouper sous un unique scénario « fournisseur indisponible » ne teste ni le contrat ni les décisions réelles.
Flux : tester les personnes, les données et le retour
Les équipes utilisent des transactions sentinelles dont le résultat est connu. Elles observent la réponse dégradée, l’entrée en file, la corrélation, le seuil d’arrêt et le rejeu. Le support doit pouvoir expliquer le statut sans accéder aux payloads sensibles.
L’exercice se termine par le retour nominal et le rapprochement des effets. Une transaction sentinelle manquante ou doublée invalide le scénario, même si les métriques de disponibilité redeviennent vertes.
Rendre le mode dégradé exerçable en trente jours
Le premier mois doit livrer une capacité étroite mais exercée : un contrat de réponse dégradée, une file bornée, une clé d’idempotence vérifiée, des seuils et un rejeu sur transactions sentinelles.
Déployer un secours limité, observable et réversible
La première semaine fixe la promesse et les opérations. La deuxième instrumente la corrélation, la fraîcheur et la file d’attente. La troisième implémente la bascule et le repli. La quatrième provoque la panne, mesure la reprise et corrige la procédure.
Le résultat attendu n’est pas un deuxième flux complet. C’est une décision reproductible lorsque le fournisseur se dégrade, avec des entrées, une responsabilité de sortie, des dépendances connues et une preuve de réconciliation.
- D’abord : isoler le cas où le référentiel répond avec douze heures de retard alors que le consommateur attend un prix applicable immédiatement et désigner la personne qui signe le périmètre avant toute correction.
- Ensuite : rapprocher identifiants d’idempotence, journaux corrélés, accusés, files d’attente et contrôles fonctionnels sur une cohorte représentative pendant au moins deux cycles complets.
- Puis : mesurer transactions protégées, fraîcheur, files différées, doubles effets, rejets et délai de réconciliation après le changement et exercer le geste de repli sous vingt-quatre heures.
- Enfin : refuser toute extension dont la preuve ne repose pas sur un contrat de dégradation précisant réponse, fraîcheur, stockage, seuil de coupure et rejeu avec un responsable et une échéance.
Le contrat de dégradation reste actif jusqu’à ce que réponse, fraîcheur, stockage et rejeu aient été exercés ensemble. L’équipe rapproche alors transactions protégées, files différées, doubles effets, rejets et délai de réconciliation. Si un plafond tient seulement grâce à une reprise manuelle, le flux reste coupé pour les nouveaux consommateurs.
Éviter les erreurs fréquentes avant le rejeu de l’intégration
La première erreur transforme toutes les erreurs en retry et surcharge le fournisseur. La deuxième met chaque message en file sans date de péremption. La troisième annonce la reprise dès que l’API répond, avant de rapprocher les effets déjà produits.
Reprise : refuser le mode manuel permanent et invisible
Un mode manuel peut stabiliser quelques transactions, mais il porte un responsable, une expiration et le même identifiant de corrélation que le flux automatique. Un export corrigé hors système sans trace commune empêche précisément la réconciliation recherchée.
Le cas du référentiel retardé doit être testé avec une lecture tolérante et une écriture interdite. Si les deux opérations reçoivent la même réponse, le contrat de dégradation est trop vague et doit être corrigé avant la mise en production.
Une réponse de secours ne doit ni mentir sur sa fraîcheur, ni perdre la requête, ni rendre le rejeu dangereux. Les files différées, rejets, doubles effets et délais de réconciliation sont donc suivis par contrat et par consommateur. La reprise attend la vidange contrôlée du stock et la confirmation métier.
Avant la réouverture, l’exploitation choisit un lot de messages expirés, un lot encore valable et une transaction dont l’effet cible existe déjà. Le circuit breaker reste fermé pendant que chaque cas est classé en abandon, rejeu ou compensation. La clé d’idempotence, l’accusé du consommateur et l’écriture métier doivent converger avant la vidange suivante. Un seul doublon replace le stock restant en quarantaine, tandis qu’un rejet explicable peut être corrigé sans rouvrir tout le trafic. Cette répétition mesure la capacité réelle de réconciliation plutôt qu’un simple retour HTTP.
Sécuriser la dégradation par le contrat et la trace
Le flux critique est relu successivement depuis la demande initiale, l’acceptation contractuelle et la trace métier nécessaire à la reprise.
Réexaminer le contrat avant de financer la sortie de dégradation
La dégradation ne peut être définie qu’après avoir nommé la promesse métier minimale, sa fraîcheur acceptable et les effets interdits. Consulter cette méthode opérationnelle. Le cadrage sépare ainsi une réponse partielle exploitable d’un faux succès qui devrait être refusé.
Il vérifie un contrat de dégradation précisant réponse, fraîcheur, stockage, seuil de coupure et rejeu après le changement, selon « Qualifier une demande d’intégration avant le budget ».
Rejouer le pack d’acceptation avant le rétablissement complet
Avant le rétablissement complet, le pack d’acceptation préparé avant le développement rejoue réponse partielle, donnée ancienne, stockage différé et coupure franche. Le consommateur signe ainsi le service encore acceptable avant qu’un incident ne force ce choix.
La deuxième lecture consacrée à la dégradation contrôlée des API sert à éprouver les définitions et les seuils retenus.
Utiliser la trace métier pour fermer chaque transaction dégradée
La trace métier de chaque transaction donne ensuite le stock exact à rejouer et les effets déjà produits. Sans cette corrélation, une dégradation apparemment protectrice peut seulement repousser des doublons vers la reprise.
La trace métier prouve finalement que la vidange des files a restauré chaque effet sans dupliquer la transaction.
Conclusion : rendre la dégradation contrôlée d’une intégration API gouvernable
Une intégration API reste maîtrisable en dégradation seulement si chaque consommateur connaît la réponse réduite, sa fraîcheur et la manière dont les écritures seront rejouées.
Un contrat de dégradation précisant réponse, fraîcheur, stockage, seuil de coupure et rejeu constitue le noyau de la démonstration. Identifiants d’idempotence, journaux corrélés, accusés, files et contrôles fonctionnels prouvent que le service réduit n’invente aucune donnée et prépare une reprise sans second effet.
La bonne décision réduit la promesse, stocke les écarts et reprend sans double effet. Le bilan rapproche les transactions protégées, la fraîcheur, les files différées, les rejets et le délai de réconciliation. Il chiffre séparément les doublons, les données anciennes, les décisions fausses et la charge de reprise manuelle.
Une API se dégrade proprement lorsque chaque consommateur connaît la fraîcheur, la réponse et la reprise qu’il recevra. Dawap formalise ce contrat, l’instrumente et le fait exercer dans ses accompagnements d’intégration API sur mesure.
