Commencer par le contrat
La documentation REST s’adresse aux machines et aux humains. Le contrat décrit paths, méthodes, paramètres, schémas et responses ; la couche humaine explique l’intention, les contraintes et les workflows.
Le happy path doit être exécutable
Montrez l’authentification, une requête complète et une réponse complète afin d’obtenir rapidement un premier succès. Les exemples doivent être valides et réalistes.
Les erreurs font partie de l’interface
Ne vous arrêtez pas à 200. Documentez authentification, validation, conflits, limites et états asynchrones, avec l’action suivante possible.
Séparer reference et guides
La reference répond « qu’est-ce qui existe ? », les guides « comment atteindre un objectif ? ». Reliez les couches au lieu de tout entasser sur une page endpoint.
Garder les exemples exécutables
Validez JSON, schémas et requêtes représentatives en CI quand c’est possible.
OpenAPI est une source, pas toute l’expérience
Utilisez OpenAPI pour la reference et la validation, puis ajoutez concepts, authentification, limites et scénarios de bout en bout.
Exemple pratique
Transformez « Bien documenter une API REST » 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 :
- 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.
Une bonne documentation API permet de prévoir l’interaction avec le système, pas seulement de reconnaître les noms d’endpoints.
Checklist éditorial rapide
- Commencer par le contrat. La documentation REST s’adresse aux machines et aux humains.
- Le happy path doit être exécutable. Montrez l’authentification, une requête complète et une réponse complète afin d’obtenir rapidement un premier succès.
- Les erreurs font partie de l’interface. Ne vous arrêtez pas à 200.
- Séparer reference et guides. La reference répond « qu’est-ce qui existe ?
