Chapitre 7.8Documentation des API

Tu peux créer l'API la plus puissante du monde, si personne ne comprend comment l'utiliser, personne ne l'utilisera.

La documentation est ce qui fait la différence entre une API adoptée et une API ignorée. C'est le mode d'emploi, la référence, le premier point de contact entre ton API et ses utilisateurs.

Stripe est souvent citée comme référence en matière de documentation d'API. Ce n'est pas un hasard si c'est aussi l'une des API les plus utilisées au monde. Un développeur qui découvre une API se pose toujours la même question, combien de temps avant que ça marche ? Si la réponse est "un après-midi", il essaie le concurrent.

Ce qu'une bonne documentation contient

Le guide de démarrage (Getting Started)

La première chose que cherche un développeur, c'est comment faire un premier appel en moins de cinq minutes. Un exemple concret, copiable-collable, qui fonctionne du premier coup.

"Installe notre SDK, colle cette clé API, exécute cette commande, et tu verras ta première réponse."

curl https://api.exemple.com/v1/clients \
  -H "Authorization: Bearer ta_cle_de_test"

Les bonnes documentations vont plus loin et fournissent une clé de test préremplie dans les exemples, pour que le développeur connecté puisse lancer la commande sans même avoir créé de compte complet. C'est un détail, et c'est pourtant ce qui transforme un curieux en utilisateur.

La référence des endpoints

Pour chaque endpoint de l'API, la documentation précise :

• L'URL et la méthode HTTP : GET /users/42, POST /orders, etc.
• Les paramètres : lesquels sont obligatoires, lesquels sont optionnels, quel type de valeur est attendu, et quelle valeur par défaut s'applique.
• Le format de la réponse : un exemple concret de ce que l'API renvoie, avec la description de chaque champ.
• Les codes d'erreur : quelles erreurs peuvent survenir et comment les traiter.
• Les limites : le nombre d'appels autorisés par minute, la taille maximale acceptée, le nombre de résultats par page.

Sur les codes d'erreur, un conseil vaut de l'or. Documente aussi les cas qui fâchent, pas seulement le scénario idéal. Un développeur passe l'essentiel de son temps à gérer ce qui rate, et une documentation qui n'explique que le chemin heureux l'abandonne exactement au moment où il a besoin d'aide. Les codes HTTP donnent la grande famille de l'erreur, le corps de la réponse doit donner le détail.

Les exemples de code

Des exemples dans plusieurs langages (JavaScript, Python, PHP, cURL) que le développeur peut copier et adapter. C'est souvent ce qui fait gagner le plus de temps.

Attention toutefois, un exemple faux est pire que pas d'exemple du tout, car il fait perdre une heure à chercher l'erreur ailleurs. C'est pour ça que les équipes sérieuses testent automatiquement les extraits de code de leur documentation, au même titre que le reste du code.

Les guides thématiques

Au-delà de la référence technique, des guides qui expliquent comment réaliser des cas d'usage courants. "Comment implémenter l'authentification", "Comment gérer la pagination", "Comment traiter les webhooks".

La différence entre les deux est simple. La référence répond à "que fait cet endpoint", le guide répond à "comment j'encaisse un paiement par abonnement". Le premier sert quand on connaît déjà l'API, le second quand on débarque. Une documentation qui n'a que de la référence oblige chaque nouveau venu à reconstituer le puzzle tout seul.

Le journal des changements

Un changelog daté qui liste ce qui a été ajouté, modifié et surtout déprécié. C'est ce que consulte un client quand son intégration se met à renvoyer une erreur du jour au lendemain. Une dépréciation s'annonce longtemps à l'avance, avec une date de fin claire, et jamais par surprise.

OpenAPI : le standard

OpenAPI (anciennement Swagger) est un standard pour décrire une API REST de façon structurée. C'est un fichier (en JSON ou en YAML) qui liste tous les endpoints, les paramètres, les réponses et les modèles de données.

{
  "paths": {
    "/clients/{id}": {
      "get": {
        "summary": "Recupere un client par son identifiant",
        "responses": {
          "200": { "description": "Le client demande" },
          "404": { "description": "Client introuvable" }
        }
      }
    }
  }
}

L'intérêt est énorme. À partir de ce fichier, des outils peuvent générer automatiquement la documentation visuelle, les SDK (bibliothèques clientes), les tests, et même le squelette du code serveur.

C'est un contrat formel entre le fournisseur de l'API et ses consommateurs. Si la spécification OpenAPI dit que le champ "email" est obligatoire et de type texte, tout le monde est aligné, et l'équipe front-end peut commencer à travailler avant même que le back-end soit prêt. C'est exactement l'idée développée dans le chapitre sur les contrats d'API.

Un mot sur les autres formats, pour ne pas être surpris en réunion. GraphQL embarque son propre schéma, qui joue le même rôle et permet aux outils d'explorer l'API automatiquement. Les protocoles plus techniques comme gRPC utilisent des fichiers de définition équivalents. Le principe ne change pas, décrire l'API dans un fichier lisible par une machine plutôt que dans un document Word.

Les SDK : simplifier l'intégration

Un SDK (Software Development Kit) est une bibliothèque que le fournisseur de l'API met à disposition des développeurs. Au lieu d'écrire les requêtes HTTP à la main, le développeur utilise des fonctions prêtes à l'emploi.

Sans SDK, pour créer un paiement chez Stripe, il faut construire soi-même la requête, poser le bon en-tête d'authentification, encoder le corps au bon format et interpréter la réponse. Avec le SDK, ça tient en une ligne.

const paiement = await stripe.paymentIntents.create({
  amount: 2000,        // le montant est en centimes
  currency: 'eur',
});

Le détail du amount: 2000 mérite qu'on s'y arrête, parce qu'il illustre parfaitement le rôle de la documentation. La plupart des API de paiement expriment les montants dans la plus petite unité de la devise, donc en centimes pour l'euro. 2000 vaut 20 euros, pas 2 000. Une documentation qui oublie de le préciser provoque des erreurs d'un facteur cent en production, et ce genre de bug se remarque très vite.

Le SDK gère les détails techniques, l'authentification, la mise en forme des données, la gestion des erreurs, les nouvelles tentatives en cas d'échec réseau. Le développeur se concentre sur la logique métier. En contrepartie, il faut maintenir ces bibliothèques dans chaque langage, ce qui représente un vrai coût pour le fournisseur.

La documentation interactive

Les meilleures documentations permettent de tester l'API directement depuis le navigateur. Tu remplis les paramètres, tu cliques sur "Envoyer", et tu vois la réponse en direct.

Des outils comme Swagger UI, Redoc ou Postman transforment une spécification OpenAPI en documentation interactive. C'est le "try it yourself" qui accélère l'adoption.

Ces outils apportent un bénéfice moins visible mais décisif. Comme la documentation est générée depuis la spécification, elle ne peut pas mentir sur la liste des endpoints ni sur le type des champs. Une documentation écrite à la main dans un coin finit toujours par diverger du code réel, et le jour où un développeur perd deux heures sur un paramètre qui n'existe plus, il ne fait plus confiance au reste.

La bonne règle est de générer tout ce qui peut l'être depuis le code ou la spécification, et de réserver l'écriture manuelle à ce qu'une machine ne saura jamais produire, les guides, les cas d'usage et les explications de contexte.

Et la documentation interne ?

Tout ce qu'on vient de voir vaut aussi pour les API qui ne sortent jamais de l'entreprise. On se dit souvent que ce n'est pas la peine, puisque l'équipe d'à côté n'a qu'à demander. Sauf que l'équipe d'à côté change, que la personne qui savait est partie, et que six mois plus tard plus personne ne sait pourquoi ce champ est optionnel.

De mon expérience, la documentation interne coûte quelques heures et fait gagner des semaines de réunions et de messages "tu sais comment marche ce endpoint ?". Elle n'a pas besoin d'être belle, elle a besoin d'exister et d'être à jour.

Une API sans documentation est comme un restaurant sans carte. Le chef a beau être excellent, les clients ne sauront pas quoi commander. Investir dans la documentation, c'est investir dans l'adoption de son API.