Comment décrire un échange entre deux systèmes

Guide d’usage Documenter

À quoi ça sert : Une flèche entre deux systèmes peut dire ce qui circule. Vous notez le protocole, l'opération, le message et les erreurs possibles.

Avant de commencer : Passez en mode Édition. Cliquez « Modifier ».

Étapes

  1. Cliquez la flèche à décrire.
  2. Dans la barre flottante, cliquez « Format d'échange ». Un clic droit sur la flèche offre « Format d'échange… ».
  3. Dans « Nature », dites le genre d'échange. Exemple : « Requête HTTP ».
  4. Dans « Protocole », « Opération » et « Message », notez les détails. Exemple fictif d'opération : « POST /v1/demandes ».
  5. Dans « Corps du message (JSON ou texte libre) », collez un exemple du message.
  6. Dans « Résultat et erreurs », notez les réponses possibles.
  7. Cliquez « Enregistrer ». Le raccourci est Ctrl+Entrée (⌘+Entrée sur Mac).

La fenêtre « Format d'échange » d'une flèche entre « Portail citoyen » et « Système de permis », champs remplis.

Les mots à connaître

  • Le protocole est la façon de communiquer. Exemple : « HTTPS · REST ».
  • Le JSON est un format de texte pour des données. Borealmap l'indente avec « Formater le JSON ».
  • « Condition » dit quand l'échange a lieu.

Bon à savoir

  • Tout est facultatif. Remplissez seulement ce que vous savez.
  • Les mêmes champs se trouvent dans « Propriétés », section « Format d'échange ».
  • Un texte qui n'est pas du JSON est gardé tel quel.
  • Les lecteurs voient le message en lecture seule. Le bouton « Copier » le copie.

Si ça ne marche pas

  • « Enregistrer » est grisé : rien n'a changé.
  • Le champ du message est en rouge : le JSON est invalide. Corrigez-le, ou gardez-le comme texte.
  • « Échange indisponible » : la flèche n'est plus dans la vue.
  • Pas de bouton « Format d'échange » : vous avez sélectionné une boîte. Sélectionnez une flèche.

Voir aussi