Vous souhaitez que davantage de personnes utilisent votre application ? La qualité de la documentation de l'API est un facteur déterminant lorsque l'on compare les fournisseurs de logiciels. Or, elle est souvent considérée comme un élément secondaire. Vous ne savez pas ce que nous entendons par API ? Consultez notre guide sur les interfaces de programmation d'applications.
Nous pensons que nous sommes plutôt doués pour rédiger des documents sur les API, mais nous aimons avoir l'avis d'autres personnes. Nous avons donc demandé à un expert (un rédacteur technique d'AWS, rien de moins) quelles étaient les meilleures pratiques en matière de rédaction de documents sur les API. Lisez ce qui suit et, en un rien de temps, vous rédigerez une documentation technique que vos utilisateurs auront envie de lire.
Allons-y.
La documentation est l'un des aspects les plus importants et les plus négligés du processus de développement de logiciels. Les équipes logicielles se concentrent souvent sur la conception et la mise en œuvre d'une fonctionnalité particulière, comme il se doit. Cependant, si vous ne mettez pas l'accent sur la documentation de l'API, votre logiciel sera difficile à utiliser. Cela est vrai même si vous parvenez à créer l'API la plus efficace, la plus sûre et la mieux conçue au monde.
La documentation de l'API est un élément central de l'expérience utilisateur (UX). C'est l'une des premières choses avec lesquelles vos clients interagissent lorsqu'ils utilisent votre API. Pour les utilisateurs potentiels, votre documentation peut être le facteur décisif dans leur choix d'adopter ou non votre logiciel.
La rédaction de la documentation d'une API peut être considérée comme une tâche fastidieuse, mais le jeu en vaut la chandelle. Dans cet article, vous découvrirez les points sur lesquels vous devez vous concentrer lors de la création de la documentation de l'API, ainsi que plusieurs conseils à garder à l'esprit lors de la rédaction. Ces conseils sont très prisés par les meilleurs professionnels de la rédaction technique. Veillez donc à les adopter dès aujourd'hui dans votre documentation sur les API.
À qui s'adresse votre documentation sur l'API ?
Avant d'entamer toute forme d'écriture, prenez le temps de réfléchir à l'identité de votre public. Cela peut vous aider à décider ce que vous devez inclure dans votre texte et sur quoi vous devez vous concentrer. Pour la documentation de l'API, votre public sera composé de deux types de lecteurs.
1. Utilisateurs existants
Il s'agit principalement des développeurs de logiciels qui utilisent déjà votre logiciel. Les utilisateurs existants sont généralement plus concernés par la documentation de référence, qui décrit des informations factuelles sur le système, telles que les paramètres de l'API, et la documentation procédurale, qui comprend des tutoriels sur la manière d'obtenir un certain résultat. Notez que vos utilisateurs existants peuvent avoir différents niveaux d'expérience dans le secteur, ainsi qu'avec votre API. Votre texte doit être facilement compris par tous les développeurs, même s'il s'agit d'ingénieurs débutants qui ne connaissent pas du tout votre produit.
2. Utilisateurs potentiels
Il peut s'agir de développeurs de logiciels, de gestionnaires de produits, d'architectes de solutions, voire de cadres supérieurs. Comme les utilisateurs potentiels ne sont pas encore vos clients, ils ont probablement un cas d'utilisation pour lequel ils ont besoin de votre API. Pour les aider à déterminer si votre API répond à leurs besoins, ils sont généralement plus intéressés par une documentation conceptuelle décrivant une fonctionnalité particulière de votre produit qui les intéresse le plus. À l'instar de vos utilisateurs existants, les utilisateurs potentiels ont également des niveaux d'expérience et d'expertise technique variables.
Veuillez noter que, par nature, la documentation sur les API est généralement classée comme un type de documentation de référence. Toutefois, cela ne signifie pas que vous devez laisser de côté les types de documentation procédurale et conceptuelle dans votre référence API. Vous pouvez incorporer les trois types de documentation pour répondre aux besoins de tous les membres de votre public, comme vous le verrez dans la section suivante.
Que doit contenir la documentation de l'API ?
Maintenant que vous savez pour qui vous rédigez votre documentation sur l'API, vous pouvez commencer à définir le contenu. Bien que les spécificités puissent varier d'un guide à l'autre, les meilleures références en matière d'API couvrent toujours les sujets suivants :
Aperçu de l'API
Toute documentation sur l'API doit commencer par une présentation de l'API. Souvent, cette présentation peut être très courte, car le nom de l'API devrait déjà vous indiquer ce qu'elle fait. Par exemple, dans la documentation AWS Lambda, la présentation de l'API DeleteAlias ne comporte qu'une seule phrase.
Toutefois, les détails importants doivent toujours être mentionnés dans la présentation de votre API. Par exemple, dans la documentation ClickSend pour l'API Mot de passe oublié, la présentation contient quelques courts paragraphes détaillant les instructions d'utilisation.
Objectifs et méthodes
Les API REST doivent inclure des points de terminaison, qui indiquent aux développeurs comment accéder à la ressource. Comme il s'agit d'une partie essentielle de votre référence API, il est souvent judicieux de la faire ressortir du reste de votre texte. En plus de vos points de terminaison, veillez également à inclure les méthodes prises en charge, telles que GET et POST.
Paramètres de l'API
Votre documentation doit énumérer tous les paramètres d'entrée de l'API. Pour chaque paramètre, vous devez inclure le type d'entrée, une brève description, les valeurs acceptées (c'est-à-dire l'expression régulière [Regex], le cas échéant) et indiquer si le champ est obligatoire. Vous pouvez voir dans la documentation de ClickSend pour l'API Send Account Verification que ces propriétés sont toutes clairement listées.
Réponse de l'API
Bien entendu, vous devez également inclure la réponse de l'API. Dans la documentation ClickSend, celle-ci est incluse dans le panneau le plus à droite sous les échantillons de code principaux, comme c'est le cas pour l'API Supprimer le contact.
Exemples de code
À la lecture de votre documentation sur l'API, vos lecteurs ne devraient avoir aucun problème à invoquer votre API. Souvent, la meilleure façon d'illustrer cela est de présenter des exemples de code. Comme nous l'avons vu dans les trois exemples précédents, ClickSend inclut des exemples de code dans les principaux langages de programmation dans le panneau le plus à droite.
Autres éléments essentiels
Votre documentation sur l'API doit également inclure et décrire suffisamment les éléments suivants :
- Codes d'état et types d'exceptions lancées
- Méthodes d'authentification
- Limites, telles que les valeurs minimales et maximales d'un paramètre
- Limites de débit, telles que le nombre maximum de requêtes API qu'un utilisateur est autorisé à effectuer avant d'être étranglé.
- Changelog, ou avis de dépréciation, le cas échéant
Meilleures pratiques en matière de documentation de l'API
Pour rédiger la meilleure documentation possible sur l'API, il ne suffit pas d'avoir une connaissance pratique des éléments à inclure. Gardez à l'esprit les meilleures pratiques suivantes lorsque vous créez et mettez à jour votre documentation.
Planifiez à l'avance
Avant d'écrire quoi que ce soit, il est toujours utile de planifier. Cela signifie qu'il faut d'abord rédiger un plan (oui, cela fait partie des meilleures pratiques, même pour la rédaction de documents). Avec un plan complet, il y a beaucoup moins de chances que vous oubliiez d'inclure quelque chose dans votre documentation.
Planifier à l'avance peut également impliquer d'envisager la mise en page finale des documents. Vous pouvez utiliser des tableaux pour organiser vos paramètres d'entrée et vos valeurs de retour. Vous pouvez également envisager d'utiliser une mise en page en deux ou trois colonnes, deux formats très répandus dans le secteur aujourd'hui. Par exemple, la documentation de l'API de Stripe contient une présentation en trois colonnes, similaire à celle de ClickSend. Comme vous pouvez le voir ci-dessous, ClickSend répertorie les actions de l'API à gauche, la description principale de l'API au milieu et des exemples de code à droite.
Les trois C
Lorsque vous essayez de communiquer quelque chose dans la documentation de votre API, vous pouvez utiliser les trois C comme lignes directrices pour la rédaction :
- Soyez clair : les concepts techniques peuvent devenir très rapidement complexes. La documentation doit avant tout être claire. Essayez d'écrire à un niveau de lecture de sixième année.
- Soyez concis : Chaque fois que vous le pouvez, privilégiez les phrases courtes. Soyez direct et simple.
- Soyez cohérent : Votre documentation doit être cohérente pour toutes les API, tant en termes de présentation que de style. Envisagez d'adhérer à un guide de style commun si plusieurs personnes contribuent à la documentation de l'API.
Évitez le jargon technique
Vous n'obtiendrez pas de points bonus en remplissant vos documents de jargon technique. En fait, l'utilisation d'un trop grand nombre de termes techniques tend à nuire à la clarté générale. Si vous devez inclure un terme technique, expliquez-le en détail ou incluez un lien vers des informations complémentaires.
En outre, veillez à ne pas inclure trop de détails sur la mise en œuvre de l'API dans votre documentation. Ce phénomène est plus fréquent chez les ingénieurs qui développent également les API qu'ils documentent. Les ingénieurs peuvent penser qu'ils doivent justifier certaines décisions en fournissant certains détails d'implémentation. Cependant, les utilisateurs ne s'intéressent généralement qu'à la manière d'utiliser votre API, et non à la manière dont elle est mise en œuvre. Les phrases qui n'apportent aucune valeur à l'utilisateur doivent être supprimées de votre documentation d'API.
Disposer d'exemples suffisants
Un manque d'exemples peut gâcher ce qui aurait pu être une excellente référence d'API. Les exemples peuvent se référer à des cas d'utilisation de haut niveau, dans lesquels vous décrivez des scénarios dans lesquels un client pourrait vouloir utiliser votre API.
Les exemples désignent également des exemples de code de niveau inférieur qui montrent des exemples d'invocations de l'API. Vous ne pouvez jamais manquer d'exemples de code dans votre documentation. De nos jours, il est d'usage de fournir des exemples dans plusieurs langages de programmation : à titre de référence, vous pouvez inclure des exemples en Python, Java, JavaScript, C# et Go. Par exemple, la documentation de l'API de Pulumi contient des exemples de code dans une liste d'onglets pour les langages les plus courants.
Envisagez des outils tels que l'OAS
L'OpenAPI Specification (O AS) est un outil populaire conçu pour vous aider à générer facilement une documentation interactive basée sur un fichier de spécification, qui contient vos structures et définitions d'API. Vous pouvez rédiger ce fichier de spécification vous-même ou le générer à partir du code en utilisant l'une des nombreuses intégrations open source de l'OAS. L'intégration est ainsi incroyablement facile et vous pouvez immédiatement commencer à créer de la documentation pour votre API.
Une autre raison d'envisager un outil tel que l'OAS est que votre API est appelée à changer au fil du temps. Outre la génération automatique de code, OAS peut également générer une nouvelle documentation en fonction des modifications que vous apportez à l'API.
Obtenir des informations sur la documentation à l'aide d'indicateurs
Au fur et à mesure que votre référence d'API s'étoffe, envisagez de mettre en place des mesures pour votre point de terminaison de documentation publique. Cela peut vous aider à déterminer les pages de documentation à privilégier. Par exemple, vous pouvez recueillir des données telles que le nombre de pages vues afin de déterminer les pages qui reçoivent le plus de trafic. Vous pouvez également prendre en compte des données telles que le taux de rebond pour savoir si les clients quittent votre documentation satisfaits de ce qu'ils ont lu.
Conclusion
Une bonne API présente deux caractéristiques : elle est à la fois bien conçue et bien documentée. Si vous devez absolument peaufiner la conception et la mise en œuvre de l'API, vous ne devez jamais négliger l'importance de la rédaction d'une bonne documentation sur l'API. La documentation vous permet de communiquer clairement aux clients comment utiliser votre API. L'adoption de votre produit par les utilisateurs peut être gravement affectée par une documentation mal rédigée.
Nous espérons que cet article vous a donné une bonne vue d'ensemble du processus de documentation de l'API. Vous avez commencé par identifier votre public cible et les éléments à inclure, puis vous avez appris certaines bonnes pratiques de documentation que vous devez garder à l'esprit lors de la rédaction de votre documentation. En évitant le jargon technique et en incluant suffisamment d'exemples, vous êtes sur la bonne voie pour produire une meilleure documentation sur les API.
Si vous avez besoin d'automatiser certaines parties de vos communications et de votre messagerie d'entreprise, pensez à ClickSend. De nombreuses entreprises de premier plan font confiance aux API de ClickSend pour envoyer facilement des SMS, des e-mails, des messages vocaux ou des courriers directs à leurs clients à grande échelle.
A propos de l'auteur
Alexander Yu 🇺🇸 Twitter : @itsxandery
Alexander Yu est rédacteur technique chez AWS le jour et rédacteur indépendant la nuit. Après avoir obtenu une licence en génie électrique et en informatique à l'université de Berkeley, il est devenu développeur de logiciels chez AWS pendant près de trois ans avant de se lancer dans la rédaction technique. Il vit à Seattle avec son chien Yuna.
