D’une requête à une doc que l’on lit
La documentation d’API pourrit parce qu’elle est écrite à côté des requêtes. La générer depuis la collection est la seule version qui reste vraie.
La plupart des documentations d’API mentent dès le troisième mois. Non parce que quelqu’un a menti, mais parce que la doc vit à un endroit et les requêtes à un autre, et qu’une seule des deux est mise à jour quand un champ change.
Lodos referme cet écart en générant la documentation à partir de la collection contre laquelle vous testez déjà. C’est tout l’intérêt d’avoir ces deux modules côte à côte, et cela change la façon d’organiser la collection dès le premier jour.
Organiser la collection pour la doc, pas pour soi
API Post/Get gère l’ensemble des méthodes HTTP, les collections avec dossiers, les en-têtes et l’authentification, et un visualiseur de réponses avec coloration syntaxique. La structure de dossiers que vous choisissez devient la structure de votre documentation : cinq minutes de réflexion valent le coup.
Groupez par ressource, pas par tâche. Un dossier users contenant lister, créer, modifier et supprimer se lit comme de la documentation. Un dossier parcours d’inscription contenant trois requêtes de trois ressources différentes se lit comme votre brouillon personnel, parce que c’en est un.
Nommez les requêtes dans le vocabulaire de l’API. GET /users/:id vaut mieux que récupérer un utilisateur, parce que la personne qui lit cherche à faire correspondre ce qu’elle voit avec l’endpoint qu’elle appelle.
Les variables d’environnement font la durée de vie
C’est la différence entre une collection qui tient un an et une qui cesse de fonctionner au premier déménagement de la préprod.
Mettez chaque hôte, chaque jeton et chaque identifiant changeant dans une variable d’environnement. {{base_url}}/users/{{test_user_id}} est une requête qui fonctionne en local, en préprod et en production en changeant un menu déroulant. Une requête avec https://staging-2.example.com figé dans l’URL casse silencieusement en trois semaines et sera réécrite par la personne suivante qui en a besoin.
Les scripts de pré-requête règlent le cas qui bloque le plus : un jeton d’authentification qui expire. Récupérez-le dans une étape préalable et stockez-le dans une variable d’environnement — vous cesserez de coller un bearer frais dans onze requêtes chaque matin.
Les identifiants, honnêtement
Une collection appartient à l’espace de travail : toute personne y ayant accès la voit, y compris les valeurs de vos environnements.
Traitez cela comme la contrainte de conception que c’est. Des identifiants de développement et de préprod dans la collection, c’est très bien et vraiment utile ; celui qui reprend votre travail ne devrait pas avoir à les chercher. Des identifiants de production, non. Si une valeur poserait problème sur une capture d’écran, elle n’a rien à faire dans un environnement partagé.
Le montage pratique : un environnement par étape, la production volontairement incomplète pour qu’un tir contre elle demande un acte conscient plutôt qu’une mauvaise sélection dans un menu.
En faire de la documentation
API Documentation génère depuis la collection, puis ajoute par-dessus un éditeur de texte enrichi, la gestion de versions, la génération d’extraits de code, l’export PDF et des liens partageables.
La partie générée couvre ce qu’est l’endpoint et ce qu’il attend. Ce qu’elle ne peut pas savoir, c’est pourquoi quelqu’un l’appellerait — et c’est justement ce dont le lecteur a besoin. Le schéma qui marche :
- Générer depuis la collection. N’écrivez pas la liste des endpoints à la main ; elle dérivera.
- Ajouter un court paragraphe par ressource expliquant à quoi elle sert et quand l’utiliser.
- Documenter les erreurs. Pas le 200 — le 409 qui signifie que l’e-mail est déjà pris, et ce que le client doit en faire.
- Publier un lien plutôt qu’exporter un PDF, sauf si quelqu’un demande précisément un fichier. Un lien reste à jour ; un PDF est la photographie d’un instant.
La gestion de versions compte dès que vous avez des consommateurs externes. Figez une version au moment où quelqu’un commence à construire dessus, pour qu’après un changement il existe encore un document décrivant ce sur quoi il a construit.
Les 130 petites choses
Bon à savoir parce que cela économise un onglet : le module Tools contient plus de 130 utilitaires — formateurs JSON et XML, encodeurs, convertisseurs, générateurs de hash. Ils s’exécutent entièrement dans votre navigateur, rien n’est envoyé, et ils ne coûtent aucun jeton.
Ce dernier détail pèse plus qu’il n’y paraît. Coller une charge utile dans un formateur JSON en ligne quelconque, c’est coller vos données sur le serveur de quelqu’un d’autre. Si elle contient les informations d’un client, c’est un petit incident que personne ne remarquera jamais. L’outil local supprime la tentation.
Questions fréquentes
Puis-je importer une collection existante ?
Les collections se construisent dans API Post/Get avec dossiers, en-têtes, authentification et environnements. Si vous venez d’un autre outil, reconstruisez les requêtes que vous utilisez réellement plutôt que de tout importer : la plupart des collections traînent des années d’endpoints morts que plus personne n’appelle.
Qui voit les identifiants de mes environnements ?
Toute personne ayant accès à l’espace de travail. Gardez-y les valeurs de développement et de préprod, laissez la production dehors. Le test est simple : si une valeur poserait problème sur une capture d’écran, elle n’a pas sa place dans un environnement partagé.
La doc se met-elle à jour quand je modifie une requête ?
La partie générée vient de la collection, donc régénérer prend le changement. Le texte écrit à la main reste tel quel — c’est pourquoi cette partie doit expliquer pourquoi un endpoint existe plutôt que répéter ses paramètres.
Exporter un PDF ou partager un lien ?
Un lien, sauf si quelqu’un a besoin d’un fichier précis. Un lien partagé reflète la version en cours ; un PDF est la photo d’un instant et commence à être faux dès le lendemain de son envoi.
