Modèle de disjoncteur pour les API tierces dans les workflows visuels

Pourquoi les pannes d'API tierces cassent plus d'une fonctionnalité

Une seule API tierce se trouve souvent au cœur du travail quotidien : prendre des paiements, vérifier des adresses, synchroniser les stocks, envoyer des messages, vérifier l'identité. Quand ce fournisseur a un problème, cela casse rarement un seul bouton. Cela peut geler des flux entiers qui ont besoin de cette réponse pour avancer.

C'est pourquoi un disjoncteur est important. Ce n'est pas une théorie. C'est un moyen pratique de garder les opérations de base en marche même quand une intégration est en mauvaise santé.

Lent et en panne nuisent différemment.

Quand une API est lente, votre workflow continue d'essayer de réussir, mais chaque étape attend. Les utilisateurs voient des écrans qui tournent, les équipes support reçoivent des tickets « ça bloque », et les tâches en arrière-plan s'accumulent. La lenteur est trompeuse parce qu'elle peut sembler être une défaillance de votre propre système.

Quand une API est en panne, vous obtenez des timeouts ou des erreurs nettes. C'est plus clair, mais souvent plus dangereux car les workflows ont tendance à relancer. Quand de nombreuses requêtes se relancent en même temps, vous créez une tempête de trafic qui rend la récupération plus difficile et peut entraîner la chute de votre propre système.

Les symptômes courants apparaissent rapidement : timeouts, files qui grossissent, mises à jour partielles et beaucoup de nettoyage manuel.

Le vrai dommage vient de la réaction en chaîne. Si un fournisseur de tarifs d'expédition est lent, la création de commande ralentit parce que le workflow refuse de confirmer la commande sans devis. Si les paiements tombent, le support peut être empêché d'émettre des remboursements même si tout le reste fonctionne.

On ne peut pas faire comme si les pannes n'existaient pas. L'objectif est de concevoir des workflows avec des chemins de repli clairs, des règles de blocage temporaires et de l'alerte pour que l'entreprise puisse continuer à prendre des commandes, servir les clients et enregistrer le travail pendant que l'intégration se rétablit.

Le disjoncteur en termes simples

Un disjoncteur est un interrupteur de sécurité pour les appels API. Quand un service tiers commence à échouer, le disjoncteur empêche votre workflow de le marteler encore et encore. Plutôt que de transformer une panne en écrans lents, timeouts et tâches bloquées, vous contrôlez le rayon d'impact.

Un disjoncteur a trois issues simples :

• Autoriser l'appel lorsque le fournisseur semble sain.
• Bloquer l'appel quand les échecs sont nombreux, et prendre immédiatement un chemin de repli.
• Tenter un appel test limité après une courte pause pour vérifier si le fournisseur est revenu.

Si vous préférez des étiquettes, ce sont « fermé », « ouvert » et « half-open ». Les noms ne sont pas l'essentiel. C'est la prévisibilité. Quand un fournisseur est malade, votre workflow doit se comporter de la même façon à chaque fois.

Cela ne masque pas les erreurs. Vous enregistrez toujours les échecs, affichez un statut clair aux utilisateurs ou à l'opération, et alertez les bonnes personnes. Vous choisissez d'échouer vite, de diriger le travail vers une alternative plus sûre, ou de faire une pause brève avant de retester.

Choisissez quels appels API ne doivent jamais stopper l'activité

Les disjoncteurs fonctionnent mieux quand vous êtes sélectif. Tous les appels fournisseurs ne méritent pas une protection spéciale. Commencez par les étapes qui, si elles sont bloquées, arrêtent l'argent, les commandes ou l'accès client.

Une méthode pratique est de suivre une demande utilisateur de bout en bout. Où un timeout forcerait-il l'utilisateur à abandonner la tâche, ou créerait-il un gâchis que votre équipe devra nettoyer plus tard ?

Les appels typiques à protéger incluent les paiements, l'expédition et la fulfillment, la connexion/SSO/MFA, les OTP et messages de confirmation, et les contrôles de conformité liés à une approbation.

Séparez aussi les étapes visibles par l'utilisateur des jobs en arrière-plan. Si quelqu'un attend sur un écran de paiement, vous avez besoin d'une décision rapide : réussir, basculer, ou arrêter avec un message clair. Pour les travaux en arrière-plan comme la synchronisation de numéros de suivi, des retries plus lents sont acceptables tant qu'ils ne bloquent pas le flux principal.

Commencez petit pour éviter l'extension du périmètre. Protégez d'abord 1 à 3 workflows, puis étendez.

Définissez ce que signifie « repli sûr » avant de construire quoi que ce soit. De bons repliements sont spécifiques et testables :

• Paiements : sauvegarder la commande en « paiement en attente » pour ne pas perdre le panier.
• Expédition : utiliser un tarif mis en cache, un tarif forfaitaire, ou confirmer la commande et retarder l'achat d'étiquette.
• Identité : autoriser la connexion par mot de passe quand le SSO est en panne, ou passer à la vérification par email.
• Messagerie : mettre les SMS en file pour plus tard et proposer une alternative quand c'est possible.

Dans l'éditeur Business Process d'AppMaster, cela devient généralement une branche propre : l'opération principale continue, tandis que l'étape dépendante du fournisseur prend une alternative contrôlée.

États, seuils et minuteries à expliquer

Un disjoncteur est un interrupteur de sécurité. La plupart du temps il laisse passer les appels. Quand le fournisseur commence à échouer, il bascule pour protéger votre workflow du temps perdu et de l'accumulation d'erreurs.

Les trois états

Fermé est la normale. Vous appelez l'API et continuez.

Si les échecs dépassent une limite, le disjoncteur devient Ouvert. Vous arrêtez d'appeler le fournisseur pendant une courte période et vous redirigez immédiatement vers un repli (valeur en cache, travail en file, flux alternatif).

Après une période de refroidissement, le disjoncteur passe en Half-open. Vous autorisez un petit nombre d'appels test. S'ils réussissent, vous revenez à Fermé. S'ils échouent, vous retournez à Ouvert.

Que mesurer

Utilisez des signaux qui correspondent à la manière dont le fournisseur échoue :

• Timeouts
• Erreurs HTTP 5xx
• Montée de la latence (trop lente pour être utile)
• Erreurs de connexion/DNS
• 429 limites de taux

Dans un outil de workflow visuel, ces signaux se traduisent souvent par des vérifications simples : code de statut, temps écoulé et sorties d'erreur spécifiques.

Seuils de départ et les deux minuteries clés

Commencez avec des chiffres faciles à expliquer, puis ajustez-les en fonction du trafic. Exemples :

• Ouvrir le disjoncteur si 5–10 appels échouent dans les 30–60 secondes.
• Ou ouvrir si 20%–40% des appels échouent sur une fenêtre glissante.
• Considérez la latence comme un échec lorsqu'elle dépasse ce que votre processus peut tolérer (souvent 2–5 secondes).

Puis configurez deux minuteries :

• Temps de cooldown (état Open) : souvent 30 secondes à 5 minutes.
• Fenêtre de test Half-open : autoriser 1–5 appels de test, ou une courte fenêtre temporelle comme 10–30 secondes.

L'objectif est simple : échouer vite quand le fournisseur est malade, récupérer automatiquement quand il est de nouveau sain.

Étape par étape : construire un disjoncteur dans un workflow visuel

Le choix de conception le plus important est de prendre la décision « devons-nous appeler le fournisseur maintenant ? » en un seul endroit, et non dispersée dans chaque workflow.

1) Placez l'appel fournisseur derrière un bloc réutilisable

Créez un sous-processus (un bloc de workflow réutilisable) que tous les workflows utilisent quand ils ont besoin de ce fournisseur. Dans AppMaster, cela correspond naturellement à un Business Process que vous pouvez appeler depuis des endpoints ou des automations. Gardez-le étroit : entrées en entrée, requête fournisseur en sortie, plus un résultat clair succès/échec.

2) Suivez les échecs avec le temps, pas seulement des comptes

Enregistrez chaque résultat avec un horodatage. Stockez des éléments comme la dernière réussite, le dernier échec, les échecs dans une fenêtre, l'état courant et une échéance de cooldown.

Persistez ces champs dans une table pour que le disjoncteur survive aux redémarrages et reste cohérent entre plusieurs instances. PostgreSQL via Data Designer convient bien pour cela.

3) Définissez les changements d'état à suivre à chaque fois

Gardez les règles simples. Exemple : si 5 échecs surviennent en 2 minutes, basculez en Ouvert. Pendant l'état Ouvert, sautez l'appel fournisseur jusqu'à ce que le cooldown soit passé. Après le cooldown, passez en Half-open et autorisez une tentative contrôlée. Si elle réussit, fermez le disjoncteur. Si elle échoue, rouvrez-le.

4) Branchez le workflow : chemin fournisseur vs chemin de repli

Avant la requête fournisseur, vérifiez l'état stocké :

• Fermé : appelez le fournisseur, puis mettez à jour succès ou échec.
• Ouvert : sautez l'appel et exécutez le repli.
• Half-open : autorisez une tentative limitée, puis décidez de fermer ou rouvrir.

Exemple : si une API d'étiquettes d'expédition est en panne, le repli peut créer la commande avec un statut « Label pending » et mettre en file un job de retry, au lieu de bloquer le checkout ou le travail en entrepôt.

5) Partagez-le entre workflows

Si vous avez plusieurs workflows et serveurs, ils doivent lire et écrire le même état du disjoncteur. Sinon, une instance peut continuer à marteler le fournisseur tandis qu'une autre a déjà décidé de faire une pause.

Repliements qui maintiennent le travail en mouvement

Un disjoncteur n'aide que si vous décidez quoi faire quand l'appel est bloqué. Un bon repli permet à l'utilisateur d'avancer, protège vos données et rend le nettoyage ultérieur prévisible.

Choisissez un repli adapté au travail. Si un fournisseur de tarifs d'expédition est en panne, vous n'avez peut-être pas besoin du prix exact pour accepter la commande. Dans un workflow visuel, orientez l'étape API échouée vers une branche de repli qui produit quand même un résultat utilisable.

En pratique, les repliements ressemblent souvent à l'un des éléments suivants :

• Utiliser une dernière valeur connue en cache (avec une fenêtre de fraîcheur claire).
• Utiliser une estimation sûre par défaut, clairement étiquetée.
• Orienter vers une revue manuelle.
• Mettre le travail en file pour retry ultérieur (job asynchrone).

L'expérience utilisateur compte autant que la logique. N'affichez pas une erreur vague. Dites ce qui s'est passé et ce que l'utilisateur peut faire ensuite : « Nous n'avons pas pu confirmer le tarif pour le moment. Vous pouvez passer la commande avec un coût d'expédition estimé, ou la mettre en attente pour révision. »

Prévoyez aussi pour les pannes courtes vs longues. Une panne courte (minutes) signifie souvent « continuer et retenter en arrière-plan ». Une panne longue (heures) peut nécessiter un comportement plus strict comme davantage de revues manuelles ou d'approbations.

Enfin, tracez chaque repli pour que la réconciliation soit facile. Au minimum, enregistrez le type de repli, les détails de la requête originale, ce qui a été renvoyé à l'utilisateur (et s'il s'agissait d'une estimation), et un statut pour le suivi.

Règles temporaires de blocage et retries plus intelligents

Les retries incontrôlés transforment de petits accrochages fournisseur en pannes réelles. Quand de nombreux workflows relancent en même temps, ils créent un pic (le problème du « thundering herd »). Le fournisseur ralentit, vos files grandissent, et vous brûlez des limites de taux.

Les retries doivent être prévisibles et limités, et respecter l'état du disjoncteur. Une politique pratique :

• Gardez le nombre maximum de retries bas (souvent 2–3).
• Utilisez un backoff exponentiel (par exemple 2s, 8s, 30s).
• Ajoutez du jitter pour éviter la synchronisation des relances.
• Limitez le temps total de retry (par exemple 60–90 secondes).
• Si le disjoncteur est Open, ne relancez pas. Allez directement au repli.

Le blocage temporaire est lié mais distinct. Il s'applique quand la réponse vous dit « ça ne fonctionnera pas pour le moment ». Règles courantes :

• 429 rate limit : bloquer pendant la période Retry-After (ou une fenêtre sûre fixe).
• 401/403 échec d'authentification : bloquer jusqu'au rafraîchissement des identifiants, puis tester une fois.
• 5xx constants : bloquer brièvement, puis autoriser un petit test.

Pendant un blocage, décidez ce qu'il advient du travail déjà en cours : le mettre en file, le réacheminer, ou dégrader gracieusement (par exemple, accepter la commande mais retarder l'envoi de SMS).

Alerting qui indique quoi faire

Un disjoncteur n'est utile que si les personnes en sont informées rapidement et savent quoi faire. L'objectif n'est pas le bruit. C'est un message clair quand le comportement change : des appels sont bloqués, des repliements sont actifs, ou le disjoncteur est resté ouvert plus longtemps que prévu.

Bons déclencheurs par défaut :

• Alerter quand le disjoncteur s'ouvre.
• Alerter s'il reste ouvert au-delà d'une durée limite.
• Alerter sur une forte montée des erreurs même avant qu'il ne s'ouvre.

Rendez les alertes actionnables. Incluez le fournisseur et l'endpoint, l'état courant et quand il a changé, ce que les utilisateurs ressentiront, ce que le workflow fait maintenant (bloque, relance, repli), et une action suggérée."

Dirigez les alertes selon la sévérité. Une API d'enrichissement non critique peut aller par email. Les paiements, la connexion ou la soumission de commande méritent généralement une page d'alerte. Dans AppMaster, cela se traduit clairement par des branches qui envoient email, Telegram ou SMS selon un flag de sévérité.

Suivez un petit ensemble de métriques pour voir si vous récupérez : les appels bloqués et l'utilisation des repliements par fournisseur suffisent souvent.

Scénario exemple : panne fournisseur sans arrêter les commandes

Une panne courante : votre fournisseur de tarifs d'expédition tombe en rade juste au moment des achats. Si votre workflow exige des tarifs en direct lors de la création de commande, une seule panne peut arrêter complètement les commandes.

En journée normale, la commande est créée, puis le workflow demande des tarifs en direct, et la commande est sauvegardée avec le transporteur et le prix choisis.

Quand le fournisseur commence à échouer, les appels timeout ou renvoient des 5xx. Une fois le seuil atteint (par exemple 5 échecs en 2 minutes), le disjoncteur s'ouvre.

Pendant l'état Open, le workflow arrête d'appeler le fournisseur d'expédition pendant une courte fenêtre (par exemple 10 minutes). Cela empêche un fournisseur défaillant d'empêcher le checkout pour tout le monde.

Au lieu de bloquer le checkout, le repli peut :

• Appliquer un tarif forfaitaire (ou une estimation sûre).
• Créer la commande quand même.
• La marquer « Shipping rate pending » pour un recalcul ultérieur.
• Enregistrer les détails d'erreur du fournisseur pour suivi.

Dans AppMaster, c'est une branche claire dans le Business Process Editor, soutenue par des champs Data Designer comme shipping_rate_status et shipping_rate_source.

Vérifications rapides avant livraison

Un disjoncteur doit se comporter de la même façon sous stress qu'en démonstration. Avant la mise en production, confirmez l'essentiel :

• Les seuils et cooldowns sont documentés et faciles à modifier.
• L'état Open bloque les appels immédiatement (sans attendre les timeouts fournisseur).
• Le comportement de repli est sûr pour l'argent et les promesses client.
• Les sondes Half-open sont limitées à quelques appels de test.
• Les logs rendent le timing et l'impact faciles à comprendre.

Passez du temps sur la sécurité des repliements. Un repli qui « permet de continuer » peut aussi créer un risque financier. Si le fournisseur de paiement est down, marquer les commandes comme payées est dangereux. Une approche plus sûre est « paiement en attente », avec un message client clair.

Testez la récupération volontairement. Forcez des échecs, observez l'ouverture du disjoncteur, attendez le cooldown et vérifiez que Half-open n'envoie qu'une petite sonde. S'il réussit, il doit se refermer rapidement. S'il échoue, il doit se rouvrir sans inonder le fournisseur.

Vos logs doivent répondre, en moins d'une minute : qui a été affecté, quand cela a commencé, quelle étape du workflow a déclenché le disjoncteur, et quel repli a été utilisé.

Prochaines étapes : implémentez le modèle dans AppMaster

Choisissez une intégration qui peut nuire aux opérations quotidiennes si elle échoue (paiements, étiquettes d'expédition, SMS, synchronisation CRM). Construisez le disjoncteur de bout en bout pour cet appel unique d'abord. Une fois que l'équipe fait confiance au comportement, répétez le même modèle pour le fournisseur suivant.

Dans AppMaster, modélisez l'état du disjoncteur dans PostgreSQL avec Data Designer. Gardez-le simple : un enregistrement par fournisseur (ou endpoint) avec des champs comme state, failure_count, last_failure_at, open_until et un court last_error.

Puis implémentez la logique dans le Business Process Editor avec des branches lisibles. La clarté bat l'ingéniosité.

Ordre pratique de construction :

1. Vérifier l'état du disjoncteur et bloquer les appels quand open_until est dans le futur.
2. Appeler l'API fournisseur et capturer les sorties succès et erreur.
3. En cas de succès, réinitialiser les compteurs et fermer le disjoncteur.
4. En cas d'échec, incrémenter les compteurs et ouvrir le disjoncteur lorsque les seuils sont atteints.
5. Orienter les flux visibles utilisateur vers un repli (mettre en file, utiliser des données en cache, ou permettre le traitement manuel).

Documentez la décision de repli en langage clair afin que le support et l'opération sachent ce que voient les utilisateurs.

Quand le disjoncteur s'ouvre, notifiez un responsable en utilisant les modules de messagerie d'AppMaster (email, SMS, Telegram). Incluez ce qui compte : fournisseur, endpoint, état et l'action recommandée initiale.

Si vous construisez ces workflows dans AppMaster, appmaster.io est un point de départ pratique car le même Business Process visuel peut alimenter endpoints, jobs en arrière-plan et alerting avec un état de disjoncteur partagé.