Documenter une API avec Mermaid : séquences, erreurs et tests HTTP

Un diagramme d’API paraît souvent complet jusqu’au premier échec. Il montre le navigateur qui appelle un point d’accès et la base qui renvoie des données, mais oublie la session expirée, la requête invalide, la limite de débit ou le délai dépassé. Ces chemins manquants sont souvent ceux dont le prochain développeur a besoin.

Un diagramme de séquence Mermaid attribue une colonne à chaque participant et une place dans le temps à chaque message. Sa source est du texte : elle se relit avec le code et se modifie sans déplacer des boîtes. L’éditeur Mermaid gratuit de Web2Generators permet de coller les exemples ci-dessous, de voir leur aperçu et de télécharger la source ou un PNG. L’annonce de l’éditeur présente les familles de diagrammes et rappelle de sauvegarder la source avant de quitter la page.

Nous allons décrire un point d’accès protégé, puis en tirer un petit plan de tests reproductible. Les URL et identifiants sont fictifs. Testez uniquement les systèmes qui vous appartiennent ou pour lesquels vous avez une autorisation.

Définir d’abord la question à résoudre

Supposons qu’un navigateur récupère les projets de l’utilisateur connecté avec GET /api/projects. L’API vérifie la session, lit les données et renvoie du JSON. Une revue technique devrait permettre de répondre à cinq questions :

1. Quel composant reçoit la requête en premier ?
2. Où l’authentification est-elle vérifiée ?
3. Quelles conditions renvoient une erreur plutôt que les projets ?
4. Le navigateur réessaie-t-il parfois l’opération ?
5. Quelles observations montreraient que l’implémentation correspond au dessin ?

Il n’est pas nécessaire de représenter chaque middleware ou requête SQL. Un diagramme des résultats visibles peut rester court même si l’implémentation est complexe. Commencez par le navigateur, l’API et la base ; ajoutez un proxy ou un cache seulement si son comportement compte pour la question posée.

Étape 1 : dessiner le parcours réussi

Collez ce code dans l’éditeur Mermaid, sans les délimiteurs du bloc Markdown :

sequenceDiagram
    autonumber
    participant Browser
    participant API
    participant DB as Database
    Browser->>API: GET /api/projects
    API->>API: Validate session
    API->>DB: Query projects for user
    DB-->>API: Project rows
    API-->>Browser: 200 OK, JSON array

participant crée les lignes de vie verticales. Une flèche pleine représente un message ; une flèche en pointillés sert couramment à indiquer une réponse. autonumber numérote les échanges pour faciliter les références pendant une revue.

La requête à la base doit être limitée, côté serveur, aux données de l’utilisateur authentifié. Écrire “Validate session” dans le diagramme ne crée pas ce contrôle dans l’application. Le dessin décrit le comportement prévu ; ce n’est pas un test de sécurité.

Cette première version suppose que chaque session est valide et que chaque opération en base réussit. Il reste à montrer les autres cas.

Étape 2 : ajouter les alternatives avec alt et else

Le bloc alt de Mermaid décrit des branches conditionnelles. Ajoutons l’absence d’authentification, l’indisponibilité de la base et le résultat normal :

sequenceDiagram
    autonumber
    participant Browser
    participant API
    participant DB as Database
    Browser->>API: GET /api/projects
    API->>API: Validate session
    alt Session missing or expired
        API-->>Browser: 401 Unauthorized
    else Valid session
        API->>DB: Query projects for user
        alt Database unavailable
            DB-->>API: Connection error
            API-->>Browser: 503 Service Unavailable
        else Query succeeds
            DB-->>API: Project rows
            API-->>Browser: 200 OK, JSON array
        end
    end

La branche imbriquée indique précisément l’origine de l’échec. 401 signifie que le client n’a pas fourni d’identifiants d’authentification valides pour cette ressource. 503 indique une indisponibilité temporaire du service ; la présence d’un en-tête Retry-After est une décision distincte de conception de l’API. Une erreur de base de données ne doit pas être appelée 401 simplement parce que l’opération ne peut pas aboutir.

Le dessin n’inclut ni mot de passe ni valeur de cookie, et ne suppose pas qu’une nouvelle tentative aura forcément lieu. Documentez le comportement effectivement implémenté.

Étape 3 : représenter CORS séparément si nécessaire

Si l’interface et l’API ont des origines différentes, le navigateur peut envoyer une requête préliminaire OPTIONS. Un GET simple authentifié par cookie ne la nécessite pas automatiquement. Un en-tête Authorization, qui ne fait pas partie des en-têtes autorisés sans cette vérification, la déclenche normalement.

Voici un diagramme centré sur cet échange :

sequenceDiagram
    participant Browser
    participant Gateway
    participant API
    Browser->>Gateway: OPTIONS /api/projects
    Note over Browser,Gateway: Origin and requested method/headers
    alt Preflight denied
        Gateway-->>Browser: Response without required CORS permission
        Note over Browser: Browser stops before the actual request
    else Preflight approved
        Gateway-->>Browser: 204 with required CORS headers
        Browser->>Gateway: GET /api/projects with Authorization
        Gateway->>API: Forward GET
        API-->>Gateway: Application response
        Gateway-->>Browser: Response with appropriate CORS headers
    end

Cet exemple conceptuel ne décrit pas tous les comportements de cache des navigateurs ni toutes les passerelles. La réponse effective doit aussi contenir les en-têtes CORS appropriés pour que JavaScript puisse la lire. Le guide de dépannage des requêtes préliminaires CORS explique les permissions du navigateur, la différence entre OPTIONS et l’authentification de l’API, et l’inspection d’un échange qui échoue.

Gardez généralement l’authentification et CORS dans des diagrammes séparés, sauf si vous expliquez un défaut qui implique les deux. Réunir toutes les branches du navigateur et du serveur rend vite le dessin illisible.

Étape 4 : utiliser un diagramme d’états pour les transitions

Un diagramme de séquence montre qui parle à qui. Un diagramme d’états répond à une autre question : dans quel état l’opération peut-elle se trouver, et quel événement la fait évoluer ?

Pour un export de rapport asynchrone :

stateDiagram-v2
    [*] --> Queued: Submit job
    Queued --> Running: Worker starts
    Running --> Ready: Export succeeds
    Running --> Failed: Export fails
    Queued --> Cancelled: Cancel accepted
    Ready --> [*]
    Failed --> [*]
    Cancelled --> [*]

Ce dessin aide à décider si le bouton Annuler doit rester visible après le démarrage du traitement. Il expose aussi les décisions manquantes : peut-on relancer un export en échec ? Cela crée-t-il une nouvelle tâche ? Si oui, ajoutez une transition explicite.

Le guide de l’éditeur Mermaid contient aussi des organigrammes, des diagrammes d’états, des modèles entité-relation et des exemples de Gantt lorsque la séquence ne convient pas.

Étape 5 : transformer les flèches en tests

Un diagramme entretenu doit conduire à des tests, pas les remplacer. Pour le point d’accès aux projets, préparez une petite matrice :

Le générateur de commandes cURL prépare les commandes localement sans envoyer de requête. Exécutez-les dans votre terminal et comparez les réponses au diagramme.

Une requête sans identifiants pourrait être :

curl --include --request GET \
  --url 'https://staging.example.com/api/projects' \
  --header 'Accept: application/json'

Pour un jeton Bearer réservé à la préproduction, utilisez une variable d’environnement plutôt qu’un vrai jeton dans la documentation :

curl --include --request GET \
  --url 'https://staging.example.com/api/projects' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $TEST_API_TOKEN"

Ce second exemple suppose un shell de type POSIX et une variable correctement définie. Si l’API attend un corps JSON, le guide JSON, formulaires et multipart explique les formats et en-têtes correspondants. Pour des paramètres répétés ou encodés, l’encodeur d’URL et éditeur de paramètres aide à examiner l’URL avant le test.

Ce que cURL permet de vérifier

Une réponse cURL montre ce qu’une requête précise a reçu à un instant donné. Elle ne prouve pas que CORS autorise JavaScript à lire la réponse, que tous les rôles sont traités correctement ou que le serveur ne comporte aucune autre vulnérabilité. Pour les comportements propres au navigateur, comparez le parcours réel dans les outils de développement. Le guide d’inspection des requêtes réseau explique comment capturer les échanges utiles.

Étape 6 : partager des diagrammes accessibles, sans secrets

La source Mermaid est du texte lisible, pratique pour les revues. Tout ce que vous y collez peut aussi finir dans un dépôt, un PNG ou un document partagé. Utilisez des domaines fictifs, des noms génériques et des libellés descriptifs plutôt que des identifiants, jetons, dossiers clients ou noms d’hôtes internes.

Ajoutez un bref résumé écrit des branches importantes. Ne faites pas dépendre la compréhension uniquement du rouge et du vert. Préférez un diagramme étroit aux libellés lisibles à une capture très large dont le texte devient minuscule sur mobile. L’éditeur exporte la source et un PNG : gardez la source avec votre documentation pour faciliter les modifications.

Quelques questions suffisent pour la relecture :

• Chaque message pointe-t-il vers le composant qui le prend effectivement en charge ?
• Distingue-t-on l’absence d’authentification, la requête invalide et l’indisponibilité temporaire ?
• Les règles de nouvelle tentative et d’annulation sont-elles explicites ?
• Méthodes HTTP, URL et statuts correspondent-ils aux tests et à la documentation de l’API ?
• Le résultat principal reste-t-il compréhensible sans les couleurs ?
• Le diagramme évite-t-il les secrets et les détails d’infrastructure privés ?

Mettre à jour le diagramme avec le code

Conservez la source Mermaid près de la spécification du point d’accès ou de son README. Lorsqu’une règle d’authentification ou un statut change, mettez le dessin à jour dans la même revue. Pour un système complexe, séparez la vue d’architecture des diagrammes ciblés sur la connexion, la récupération des données et les parcours de reprise.

L’objectif est de réduire les hypothèses pendant le prochain diagnostic. Décrivez un point d’accès réel dans l’éditeur Mermaid, puis utilisez le générateur cURL pour vérifier un succès et un échec avant de partager le diagramme.