Une API sans documentation fonctionne quand même, tant que la personne qui l’a écrite reste disponible pour répondre aux questions. Le problème apparaît dès qu’une autre équipe, une agence partenaire, une application mobile ou un nouveau développeur doit s’y connecter sans cette aide directe : chaque question devient un aller-retour, chaque hypothèse un bug potentiel.
Ce qu’une documentation minimale doit contenir
- La liste des points d’accès (endpoints), avec la méthode HTTP et l’objectif de chacun.
- Les paramètres attendus, leur type, et s’ils sont obligatoires.
- Un exemple de requête et un exemple de réponse réels, pas seulement une description abstraite.
- Les codes d’erreur possibles et leur signification.
- Le mode d’authentification, avec un exemple concret.
- Les limites d’usage, s’il y en a (nombre de requêtes par minute, taille des pages de résultats).
Décrire l’API avec OpenAPI
Le standard OpenAPI (anciennement Swagger) décrit une API dans un fichier que des outils transforment en documentation interactive, avec un espace pour tester les requêtes sans quitter la page. Un extrait :
paths:
/api/v1/commandes/{numero}:
get:
summary: Détail d'une commande
parameters:
- name: numero
in: path
required: true
schema: { type: string, example: A-1042 }
responses:
'200': { description: La commande }
'404': { description: Commande introuvable }Ce fichier n’a pas besoin d’être écrit à la main. Sur Laravel (Scramble, L5-Swagger) comme sur Symfony (NelmioApiDocBundle, API Platform), il peut être généré à partir des routes, des règles de validation et des attributs PHP 8 existants, ce qui limite le risque qu’il devienne obsolète.
Des erreurs prévisibles
Une API agréable à utiliser renvoie toujours ses erreurs dans le même format, avec un message compréhensible et le détail des champs en cause :
{
"message": "Les données envoyées sont invalides.",
"errors": {
"email": ["Le champ e-mail doit être une adresse valide."]
}
}Le développeur qui intègre l’API sait alors quoi afficher à l’utilisateur, sans deviner.
Versionner et annoncer les changements
- Préfixez les adresses par une version (
/api/v1/) : le jour où un changement casse la compatibilité, la v2 cohabite avec la v1 le temps que les clients migrent. - Tenez un journal des modifications : ce qui a été ajouté, modifié, déprécié, avec la date.
- Fournissez une collection prête à l’emploi (Postman, Bruno, Insomnia) : le partenaire teste en quelques minutes au lieu de reconstituer chaque requête.
Le vrai gain : moins d’allers-retours
Une bonne documentation ne sert pas seulement les partenaires externes. En interne, elle évite les questions répétées, accélère l’arrivée d’un nouveau développeur, et sert de garde-fou : si le comportement réel de l’API diverge de sa documentation, c’est souvent le signe d’un bug ou d’un changement non maîtrisé. Pour une agence qui sous-traite une partie du développement, c’est aussi ce qui permet de reprendre le projet sans dépendre d’une seule personne.
Documenter au fil de l’eau, pas à la fin
La documentation écrite après coup, une fois le projet terminé, est rarement complète et vite dépassée. La produire au moment où chaque point d’accès est créé, pendant que le contexte est encore frais, coûte quelques minutes et évite des heures de reconstitution plus tard.
La check-list
- Chaque point d’accès : méthode, objectif, paramètres, exemples de requête et de réponse.
- Authentification expliquée avec un exemple.
- Format d’erreur unique, codes documentés.
- Description OpenAPI générée depuis le code.
- Version dans l’adresse, journal des modifications.
- Collection de requêtes prête à l’emploi.
Pour aller plus loin : mon expertise : Développeur Laravel freelance · à lire aussi : Files d’attente et tâches en arrière-plan : pourquoi votre application en a besoin
