Diagrammes de séquence Mermaid pour appels API et services

Les diagrammes de séquence expliquent l’ordre des interactions. Ils conviennent mieux qu’un organigramme lorsque la question est « qui envoie quoi à qui, et quand ? ». Ils servent aux appels navigateur-API, authentifications, webhooks, files d’attente et retries entre services.

Déclarer des participants bien nommés

sequenceDiagram
  actor User as Utilisateur
  participant Web as Application web
  participant API as API des commandes
  participant DB as Base de données
  User->>Web: Envoyer la commande
  Web->>API: POST /orders
  API->>DB: Insérer la commande
  DB-->>API: ID de commande
  API-->>Web: 201 Created
  Web-->>User: Afficher la confirmation

Les alias gardent les messages courts tout en affichant des noms lisibles. Utilisez un acteur pour un rôle humain et des participants pour les composants logiciels. Ordonnez-les selon le chemin principal.

Distinguer appels et réponses

Les flèches pleines représentent généralement les requêtes et les flèches pointillées les réponses. C’est une convention, pas une garantie de synchronisme. Précisez le caractère bloquant ou asynchrone dans le libellé si nécessaire.

Montrer des alternatives sans dupliquer

sequenceDiagram
  Client->>API: GET /profile
  alt jeton valide
    API-->>Client: 200 Profil
  else jeton expiré
    API-->>Client: 401 Unauthorized
  end

Utilisez alt pour des issues alternatives, opt pour une branche facultative et loop pour une répétition. Le libellé doit décrire la condition plutôt qu’une fonction interne.

Rester honnête sur le temps et les responsabilités

L’axe vertical n’est pas une chronologie précise. Ajoutez des mesures dans les messages si la latence compte. Modélisez les interactions entre frontières importantes, pas chaque appel de fonction interne.

Testez l’exemple dans l’éditeur de diagrammes Mermaid et exportez en SVG pour garder des lignes nettes.