Documenter un workflow d’intégration d’API

Ce qu’il faut y mettre

• Les acteurs en couloirs : utilisateur, frontend, votre backend, chaque service tiers.
• Les appels dans l’ordre, avec méthode et chemin.
• Les décisions sur les réponses : succès, erreur client, erreur serveur, délai dépassé.
• Les relances et leurs limites.
• Les étapes asynchrones : webhooks, interrogations périodiques, files de messages.
• Les états finaux : ce que voit l’utilisateur et ce qui est enregistré dans chaque cas.

Exemple : le paiement par carte

1. Frontend : le client confirme la commande.
2. Backend : crée un paiement chez le prestataire (POST /payments).
3. Décision : quelle réponse ?
   • Créé → attendre la confirmation.
   • Refusé → afficher « carte refusée », fin.
   • Délai dépassé ou erreur serveur → relancer.
4. Relancer jusqu’à 3 fois avec un délai croissant ; ensuite, marquer la commande « paiement en attente » et alerter le support.
5. Prestataire : envoie un webhook quand le paiement réussit ou échoue.
6. Backend : vérifie la signature du webhook, met à jour la commande, envoie le reçu.

Dessiné en couloirs, le schéma montre clairement que le statut de la commande dépend du webhook et non de la première réponse, une source fréquente de bugs.

Bien représenter les relances

Une relance est une boucle, et toute boucle doit avoir une sortie, comme expliqué dans conditions et boucles. Écrivez la limite sur le schéma (« 3 tentatives max ») et dessinez ce qui se passe après le dernier échec. Si un appel peut être relancé sans risque, indiquez comment l’idempotence est garantie, par exemple avec une clé d’idempotence, pour que le lecteur sache que les doublons sont gérés.

Webhooks et attente

Représentez l’attente explicitement avec une étape de délai (« Attendre le webhook du prestataire ») et une branche de dépassement (« Pas de webhook après 15 minutes → interroger le statut du paiement »). Sans ce délai, le schéma laisse entendre que le système peut attendre indéfiniment.

Logigramme, diagramme de séquence, ou les deux

Le logigramme répond à « que se passe-t-il dans chaque cas ? ». Le diagramme de séquence répond à « qui appelle qui, dans quel ordre ? ». Pour les intégrations complexes, gardez les deux côte à côte dans le dépôt, en code Mermaid sur GitHub.

Partir de la spécification

Si l’API tierce publie un fichier OpenAPI, importez-le pour obtenir les noms exacts des endpoints sur chaque étape automatique ; voir d’OpenAPI au logigramme. Pour la connexion, l’inscription et le renouvellement de jeton, le guide des parcours d’authentification liste les branches que l’on oublie souvent.

Esquissez votre logigramme d’intégration.