Lorsqu’un consommateur achète un nouveau gadget, un appareil ou un logiciel, le manuel d’utilisation est essentiel pour savoir ce que fait cet appareil ou ce logiciel. La même logique peut être appliquée à une interface de programmation d’application ou une API via sa documentation. Les « docs » servent de guides de référence pour compiler les informations essentielles, les didacticiels et les exemples de code pour illustrer le fonctionnement de l’API.
Les docs d’API sont souvent la première chose que les développeurs regardent lorsqu’ils décident d’adopter ou non un produit donné. Cela donne du crédit à l’adage selon lequel une API n’est jamais aussi bonne que sa documentation. Si elle n’est pas accompagnée d’une documentation fiable, l’API peut ne jamais voir le jour. C’est pourquoi les concepteurs d’API investissent désormais davantage dans cette partie du processus de développement. Une façon d’y parvenir est de mettre en œuvre une documentation d’API hébergée par des experts en API comme Stoplight. L’utilisation de solutions open-source comme les suites d’outils de documentation d’API donne aux concepteurs l’avantage de publier une documentation belle et fonctionnelle.
De nos jours, il existe quatre types courants de documentation d’API : les documents marketing, les guides de référence, les guides thématiques approfondis et les exemples de « recettes » de code qui peuvent être copiés-collés. Chacune de ces approches de documentation constitue quelque chose de différent, et chacune peut avoir plus de valeur pour une partie prenante que pour une autre. Cette rubrique vous présentera les quatre types de documentation ainsi que leurs avantages et inconvénients respectifs. Si vous faites partie d’une équipe API, cela devrait vous aider à déterminer le meilleur type de documentation à avoir. Cela vous aidera à choisir le format qui communique le mieux la valeur de votre API aux clients potentiels.
Matériel de marketing de l’API
Les supports marketing peuvent être considérés comme le » guide du mannequin » de l’API. Il s’agit d’éléments de contenu, de brochures, d’illustrations, etc., et ils sont souvent le fruit d’une collaboration entre des rédacteurs, des graphistes et des concepteurs Web. Lorsque l’on lit des documents de marketing pour l’API, on ne s’attend pas à ce qu’ils soient trop techniques – juste assez pour permettre une connaissance superficielle du produit.
Les avantages des supports marketing de l’API : S’ils sont rédigés dans un langage simple et accompagnés d’illustrations claires, les documents de marketing peuvent être extrêmement utiles pour faire comprendre l’API aux personnes qui ne sont pas des techniciens. Les personnes qui utilisent ce type de document peuvent être des développeurs, des chefs de produit des entreprises clientes, et même des utilisateurs finaux. Ils peuvent repartir avec au moins une idée pratique de ce que le produit est censé faire.
Les inconvénients des documents marketing sur les API : L’inconvénient des supports marketing est qu’ils ne peuvent jamais donner qu’une introduction superficielle à l’API. Si vous montrez les documents à des personnes plus expérimentées en matière de développement d’API, elles peuvent exiger quelque chose de plus détaillé en plus des documents. C’est à ce moment-là que vous devez opter pour un format de documentation d’API plus substantiel.
Guides de référence sur l’API
Les guides de référence sur les API sont un type de documentation destiné à couvrir toutes les bases de l’API. Il peut s’agir de la mission de l’équipe de conception de l’API, de sujets universels, des points de terminaison et des paramètres de l’API, d’une liste de mises à jour et de quelques questions fréquemment posées. Il s’agit de la forme de documentation qui se rapproche le plus d’un manuel d’utilisation typique d’un produit.
Les avantages des guides de référence d’API : Il s’agit d’un moyen simple de documenter l’API. Il peut être rédigé et mis en page comme un guide de l’utilisateur pour tout autre produit. La vue peut être réconfortante pour un développeur, et il aura l’impression que l’équipe de conception est minutieuse, méticuleuse et digne de confiance dans son travail.
Les inconvénients des guides de référence d’API : Bien que le guide de référence semble être une méthode infaillible pour documenter l’API, il peut également être considéré comme trop « vanille » ou banal. Compte tenu de la créativité dont font preuve les autres équipes de conception d’API dans leurs documents, les utilisateurs finaux du produit peuvent souhaiter une documentation plus intéressante.
Guides thématiques approfondis sur l’API
De même nature que les guides de référence, les guides thématiques approfondis couvrent des aspects spécialisés de l’API. Ces derniers exigent une connaissance avancée de l’API et couvrent généralement la résolution de problèmes de haut niveau, les questions administratives sur l’API, etc.
Les avantages des guides thématiques approfondis pour l’API : Le fait de disposer de guides topiques approfondis peut être très rassurant pour le marché cible de l’IPA, car il sait que toutes les bases de l’IPA sont couvertes. Plus la liste des guides thématiques est longue et complète, plus l’IPA peut sembler précieuse pour le consommateur.
Les inconvénients des guides thématiques approfondis pour les IPA : Le principal inconvénient des guides thématiques approfondis pour la documentation de l’API est qu’il existe un risque de surcharge d’informations. La rigueur des guides peut ne rien vouloir dire si les utilisateurs les trouvent denses au point d’être incompréhensibles.
Recettes de copier-coller du code API
Dans la sphère actuelle du développement des API, ce type de documentation s’avère être le plus populaire. Grâce aux outils hébergés de documentation des API, les développeurs peuvent copier-coller et tester des échantillons du code de l’API dans un environnement de test contrôlé. Ils verront par eux-mêmes comment le code de l’API peut fonctionner pour les tâches qu’ils souhaitent effectuer.
Les avantages du code API copié-collé : Cette forme de documentation est la plus pratique des quatre. Elle permet aux développeurs de jouer avec le code, de le bricoler et de l’adapter à leurs besoins. La possibilité de travailler avec des « recettes » de code et de les transformer en appels d’API réussis peut être l’un des principaux arguments de vente de l’API.
L’inconvénient du code d’API copié-pâté : Le problème le plus prévisible des tests et de la documentation des API basés sur des recettes est qu’ils peuvent conduire les développeurs à se focaliser sur le fonctionnement d’une ou deux recettes. Il est important de les orienter vers la « vue d’ensemble » de l’API et pas seulement vers quelques blocs de code fonctionnel. De plus, la documentation de l’API en tant que code ne fonctionnera vraiment que si les échantillons de code sont pertinents pour les utilisateurs finaux. La clé est d’adapter le système aux situations et au contexte de la vie réelle.
Comment choisir le bon type de documentation d’API ?
En fin de compte, vous n’êtes pas limité à un seul type de documentation d’API. Vous pouvez combiner différents types de documents ou investir dans une plateforme qui permet de les combiner.
Quelle que soit la façon dont vous choisissez de documenter vos API, gardez toujours vos utilisateurs finaux à l’esprit. Donnez-leur des informations, des instructions et des exemples concrets pour les convaincre d’acheter votre API. Une fois qu’ils auront appris à connaître le produit grâce à ce que la documentation de l’API leur montre, il est probable qu’ils adopteront votre produit. D’ici là, n’oubliez pas de faire des efforts supplémentaires pour choisir, formater et publier la documentation de votre API.