Valide n’est que le début
Un exemple dérivé d’un schema peut être syntaxiquement correct et n’enseigner presque rien. string, 123 et foo satisfont des validateurs mais masquent le domaine. Un bon exemple montre pourquoi la request existe et ce que la réussite permet ensuite.
Utilisez des valeurs réalistes sans vrais secrets ni données personnelles.
Construisez une petite histoire
Préférez une séquence proche d’une tâche réelle : créer une ressource, la lire, la mettre à jour, puis gérer une erreur ou un cleanup. Réutilisez les identifiers afin que les relations soient visibles.
Sur les pages de reference, liez vers le workflow pertinent au lieu de copier un tutoriel complet.
Montrez la réponse importante
Ne vous arrêtez pas à la request. Incluez status, headers utiles et body. Expliquez les champs peu évidents. Si l’opération est asynchrone, montrez comment le client sait qu’elle est terminée.
Les erreurs méritent le même soin : une vraie validation error peut enseigner plus qu’un autre happy path.
Rendez les exemples exécutables
Quand c’est possible, exécutez les requests en CI ou validez les payloads contre le contract. Stockez les samples comme fichiers ou snippets générés, pas comme copies manuelles dispersées.
Optimisez pour l’adaptation
Expliquez quelles valeurs le lecteur doit changer et quels postulats doivent rester vrais. L’objectif est de transférer un modèle mental.
Si l’exemple ne rend pas la prochaine requête plus facile à concevoir, il est probablement décoratif.
Exemple pratique
Transformez « Les exemples d’’API doivent enseigner un workflow, pas décorer la référence » en une tâche développeur complète. Utilisez une ressource fictive mais réaliste — rapport, appareil ou commande — et décrivez le chemin le plus court de l’authentification au résultat réussi. Incluez la requête, les champs importants de la réponse, une erreur probable et l’action suivante.
Relisez l’exemple comme si vous construisiez réellement un client : Pour « Les exemples d’’API doivent enseigner un workflow, pas décorer la référence », gardez le test centré sur la décision précise proposée par l’article.
- quelles valeurs doivent être remplacées ;
- quels identifiants sont renvoyés puis réutilisés ;
- quel statut ou champ confirme le succès ;
- que faire en cas de credentials, données ou limites incorrects.
- Pour « Les exemples d’’API doivent enseigner un workflow, pas décorer la référence », définissez avant de commencer un critère observable de réussite ou d’échec.
Une bonne documentation API permet de prévoir l’interaction avec le système, pas seulement de reconnaître les noms d’endpoints. L’exercice vérifie ainsi précisément « Les exemples d’’API doivent enseigner un workflow, pas décorer la référence » au lieu de devenir un audit documentaire générique.
Checklist éditorial rapide
- Valide n’est que le début. Un exemple dérivé d’un schema peut être syntaxiquement correct et n’enseigner presque rien.
- Construisez une petite histoire. Préférez une séquence proche d’une tâche réelle : créer une ressource, la lire, la mettre à jour, puis gérer une erreur ou un cleanup.
- Montrez la réponse importante. Ne vous arrêtez pas à la request.
- Rendez les exemples exécutables. Quand c’est possible, exécutez les requests en CI ou validez les payloads contre le contract.
