Votre documentation d'API liste 47 endpoints. Chacun a sa méthode HTTP, son chemin, son corps de requête et son schéma de réponse. C'est complet, précis, et totalement inutile.
Pourquoi ? Parce que quand j'arrive sur votre documentation, je ne veux généralement pas un inventaire d'endpoints.
Je veux accomplir une tâche.
Je veux savoir comment créer le client, attacher le moyen de paiement, démarrer l'abonnement, gérer le webhook, récupérer après une erreur, et tester le tout en toute sécurité.
La référence des endpoints est nécessaire. Ce n'est pas le produit.
La référence n'est pas l'intégration
Une page de référence répond à :
- quel chemin existe
- quelle méthode il accepte
- quels champs sont autorisés
- à quoi ressemble la réponse
L'intégration répond à :
- que dois-je faire en premier ?
- dans quel ordre ces appels s'enchaînent-ils ?
- qu'est-ce qui peut échouer ?
- que dois-je stocker ?
- comment tester sans casser la production ?
Si votre documentation ne contient que des pages de référence, le développeur doit reconstruire le workflow à partir de pièces détachées.
C'est pourquoi une documentation "complète" peut encore sembler inutilisable.
Commencez par les tâches réelles des développeurs
Pour la plupart des API, la vraie documentation devrait commencer par des parcours de tâches :
- authentifier une requête
- créer la première ressource
- mettre à jour la ressource en toute sécurité
- écouter un webhook
- réessayer une opération échouée
- passer du mode test à la production
Chaque tâche peut ensuite rediriger vers la référence des endpoints.
Le guide commence par l'objectif du développeur, montre un chemin fonctionnel, inclut des exemples, puis redirige vers les détails précis des endpoints.
L'ordre compte. Si la première page est un énorme tableau de référence, vous demandez au lecteur de construire le modèle mental tout seul.
Montrez un chemin complet, pas des appels isolés
Les mauvaises documentations montrent une requête parfaite :
POST /customersLes meilleures documentations montrent la séquence :
- Créer le client.
- Créer l'abonnement.
- Stocker les identifiants retournés.
- Écouter le webhook de confirmation.
- Gérer les états d'échec et d'annulation.
La séquence est ce dont les développeurs ont besoin pour livrer l'intégration.
Encore mieux, incluez la forme de la machine à états :
La documentation des erreurs fait partie de l'intégration
Une API sérieuse dit aux développeurs quoi faire quand les choses échouent.
Ne vous arrêtez pas à :
{ "error": "invalid_request" }Documentez :
- si la requête peut être réessayée en toute sécurité
- si l'opération a pu partiellement réussir
- quelles erreurs nécessitent une action de l'utilisateur
- quelles erreurs nécessitent une action de l'opérateur
- quel identifiant envoyer au support
- si le webhook fait autorité
C'est là que la documentation d'API devient une infrastructure de confiance.
Utilisez des exemples qui reflètent la réalité de la production
L'exemple ne doit pas être un jouet si le workflow de production n'en est pas un.
Mauvais :
{ "name": "John" }Meilleur :
{
"externalId": "acct_123",
"email": "operator@example.com",
"plan": "studio-audit",
"metadata": {
"source": "route-finder",
"campaign": "content-engine"
}
}Le meilleur exemple enseigne le nommage, les métadonnées, l'idempotence et l'attribution. Il aide le développeur à construire le vrai système.
Ajoutez une checklist avant la mise en production
Chaque API ayant un impact métier réel devrait inclure une checklist de mise en production.
Cette checklist ne remplace pas la référence. Elle rend la référence utilisable.
Rendez la documentation testable
Les meilleures documentations d'API sont suffisamment proches du système pour pouvoir échouer quand le système change.
Cela peut signifier :
- des exemples générés à partir de schémas typés
- des exemples de requêtes validés en CI
- la sortie OpenAPI vérifiée par rapport aux gestionnaires de routes
- les liens de documentation vérifiés à chaque build
- des tests de contrat pour le workflow public
Si la documentation est maintenue manuellement loin du code, elle dérivera. Quand elle dérive, les développeurs cessent de lui faire confiance.
La structure que j'apprécie
Pour une API sérieuse, je livrerais cette architecture de l'information :
- Commencez ici : ce que fait l'API et ce que vous pouvez construire.
- Démarrage rapide : un parcours complet sans erreur.
- Authentification : clés, périmètres, rotation, configuration locale.
- Workflows principaux : guides basés sur les tâches.
- Webhooks/événements : livraison, réessais, signatures, rejeu.
- Erreurs/réessais : ce qui a échoué et quoi faire.
- Référence : détails au niveau des endpoints.
- Checklist de production : garde-fous pour la mise en production.
- Journal des modifications : changements cassants et notes de migration.
Ce n'est pas excessif. C'est ce qui permet à quelqu'un de s'intégrer sans qu'un ingénieur commercial soit assis à côté de lui.
