Article original : How to Write Good API Documentation
Imaginez acheter un ventilateur sur pied directement sorti de la boîte, toutes les pièces démontées, et vous n'avez aucun manuel ou guide pour les assembler. Vous venez de l'imaginer ? Bien.
Voici un autre scénario : imaginez acheter un produit LG, comme une télévision intelligente sans guide sur la façon de la configurer et d'utiliser la télécommande. Maintenant, vous comprenez.
Le processus de montage de votre ventilateur ou de configuration de votre télévision intelligente sera très frustrant et confus sans aucun guide. Et la plupart du temps, il sera difficile de déterminer le plein potentiel du produit que vous avez acheté.
Maintenant, en gardant à l'esprit les scénarios déjà décrits, avez-vous déjà essayé d'apprendre un nouveau langage de programmation ou d'utiliser une API inconnue, pour la trouver confuse, et vous vous êtes senti complètement dépassé au début ? Ensuite, vous avez probablement passé des heures à essayer de rassembler les choses, peut-être via des tutoriels, mais rien ne semble fonctionner parfaitement à cause des messages d'erreur que vous recevez... et vous vous demandez si vous faites la bonne chose.
Mais ensuite, vous êtes peut-être tombé sur la documentation officielle du produit ou peut-être un guide bien écrit et bien structuré (comme celui que vous lisez). Soudain, tout devient clair, vous commencez à écrire du code sans effort ou à utiliser l'API avec confiance. C'est ça - le pouvoir d'une documentation claire et concise.
Dans cet article, vous apprendrez ce qu'est une API, comment elle fonctionne, en quoi consiste la documentation des API et comment créer une documentation standard pour les API.
Plongeons-nous dans le sujet.
Plan
Avant de continuer, faisons une petite digression pour apprendre ce que sont les API, comment elles fonctionnent et les types d'API qui existent.
Qu'est-ce qu'une API ?
Vous avez peut-être déjà entendu le terme API, et vous vous demandez ce que c'est. API signifie Application Programming Interface. Une API agit comme une interface entre deux programmes qui leur permet de communiquer. C'est un médiateur entre le client (navigateurs/application mobile) et le serveur (backend).
Comment fonctionnent les API
Maintenant que vous savez qu'une API agit comme un pont ou un intermédiaire qui permet à deux systèmes de communiquer entre eux. Lorsque vous travaillez avec des API, vous rencontrerez deux termes clés : requêtes et réponses. Ces deux mots-clés sont essentiels à comprendre car ils forment le cœur du fonctionnement des API.
Pensez aux requêtes et aux réponses comme ce que vous utilisez dans une conversation quotidienne. C'est comme lorsque vous posez des questions (requête) et qu'une réponse est fournie (réponse). La même chose se produit avec les API, mais dans ce cas, il s'agit d'une interaction entre des systèmes logiciels.
Pour mieux expliquer comment fonctionne une API, utilisons une application météo ou une application de bourse. Cela devrait fournir une vue claire de ce dont nous parlons.
Lorsque vous ouvrez une application météo et que vous souhaitez vérifier la météo actuelle, l'application ne stocke pas elle-même les données météo. Au lieu de cela, elle envoie une requête via une API au serveur de la base de données météo. Lorsque la requête est envoyée, l'API interagit/communique avec le serveur de la base de données et récupère les dernières informations météo, qui sont ensuite renvoyées à l'application météo en tant que réponse. Ensuite, ces informations sont enfin affichées pour vous.
Ce processus doit être fluide, rapide et continu et doit se produire simultanément pour que votre application fonctionne correctement. Cela signifie qu'une requête doit être faite en premier avant qu'une réponse ne puisse être reçue. Vous ne pouvez pas obtenir de réponse sans faire de requête.
Le même processus se produit pour l'application de bourse également.
Types d'API
Les API sont classées en deux grands types :
Par utilisation/fonction
Par accès
Types d'API par utilisation
API Web : Ce sont les types d'API les plus couramment utilisés et sont également connus sous le nom d'API HTTP (Hypertext Transfer Protocol). Cette API permet la communication via Internet en utilisant HTTP. Des exemples de ces API sont les API REST, les API GraphQL, etc.
API de bibliothèque ou de framework : Ce sont des API fournies par des bibliothèques ou des frameworks et sont utilisées par les développeurs pour construire des applications sans avoir à tout construire à partir de zéro. Des exemples de cela sont React, JQuery, etc.
API de système d'exploitation : Ce sont des API construites pour permettre aux systèmes/applications de communiquer avec les systèmes d'exploitation. Ces API aident à fournir l'accès aux ressources au niveau du système, ce qui est important pour que l'application fonctionne correctement. Des exemples de ces API sont Android SDK, Windows API, etc.
API matérielles : Ce sont des API construites pour permettre aux systèmes de communiquer avec les composants physiques d'un périphérique matériel. Des exemples de ces API sont les API Bluetooth, les API de caméra, etc.
API de base de données : Comme leur nom l'indique, ce sont des API qui permettent aux applications d'interagir avec la base de données. Ces API sont essentielles et principalement utilisées pour stocker, récupérer, gérer et mettre à jour la base de données. Des exemples de ces API sont les API basées sur SQL, les API NoSQL, etc.
Types d'API par accès
API ouvertes : Cela peut être vu comme une API publique et est également appelée API externes. Ce sont les types d'API construites et mises à disposition pour que tout le monde puisse les utiliser, ce qui les rend peu ou pas du tout nécessaires en termes d'autorisation et d'authentification. En fonction du nombre d'appels effectués à ces API, certaines d'entre elles sont disponibles gratuitement tandis que d'autres sont disponibles à un coût spécifique (abonnement payant).
API partenaires : Ce sont des types d'API construites et mises à disposition uniquement pour les entreprises qui collaborent ensemble. Lorsque ce type d'API est construit, un processus d'authentification et d'autorisation solide est pris en considération afin d'éviter qu'il ne soit accessible au public.
API internes : Les API internes peuvent également être appelées API privées. Ces API sont construites et utilisées en interne par une organisation et sont restreintes au public. Ces API sont principalement utilisées lorsqu'il y a une communication entre des systèmes ou des applications au sein de l'organisation.
API composites : Il s'agit d'un type d'API construit de manière à combiner plusieurs requêtes d'API en un seul ensemble et à permettre aux utilisateurs d'obtenir une seule réponse de différents serveurs. Ce type d'API est le plus couramment utilisé lorsque les développeurs doivent récupérer des données de plusieurs serveurs ou sources de données.
Maintenant que nous avons décomposé ce que sont les API, comment elles fonctionnent et leurs différents types, passons à la raison principale pour laquelle nous sommes ici : apprendre à créer une bonne documentation d'API.
Qu'est-ce que la documentation des API ?
La documentation des API est également appelée documentation pour développeurs. Il s'agit d'un guide ou d'un manuel bien écrit et organisé qui explique comment fonctionne une API. Il est conçu pour aider les développeurs (ou même les non-développeurs) à comprendre ce que fait l'API, comment l'utiliser et comment l'intégrer dans leurs propres projets.
En utilisant la documentation des API, vous pouvez explorer et tirer pleinement parti de tout ce qu'une API a à offrir. La documentation des API vise également à accélérer le processus de développement et à stimuler la productivité globale d'un produit.
La documentation des API fournit une explication détaillée de la fonctionnalité complète de l'API, qui peut inclure :
La manière la plus efficace d'utiliser l'API
Comment intégrer l'API avec votre projet.
Le but de l'API et les entrées à passer pour que les développeurs puissent en faire bon usage.
Exemples de documentation des API
Voici quelques exemples de documentation des API pour vous donner une meilleure idée de ce qui est impliqué et des informations que ces documents doivent fournir.
Documentation de l'API Stripe
Il s'agit d'un exemple d'API Web/HTTP. Stripe est un outil de traitement des paiements, et la documentation de l'API Stripe fournit un guide propre, interactif et convivial pour les développeurs sur la façon d'utiliser l'API pour les intégrations de paiement.
Documentation de React
La documentation de React est un exemple d'API de bibliothèque ou de framework. Elle fournit un guide détaillé sur la façon d'utiliser React pour construire votre projet web.
Android SDK
Il s'agit d'un exemple d'API de système d'exploitation. La documentation de l'API Android SDK fournit un guide détaillé sur la façon d'utiliser l'API Android SDK pour construire votre application Android.
API Web Bluetooth
Il s'agit d'un exemple d'API matérielle. La documentation de l'API Web Bluetooth fournit un guide détaillé sur la façon d'utiliser l'API pour se connecter et interagir avec des périphériques Bluetooth à faible consommation.
API PostgreSQL
Il s'agit d'un exemple d'API de base de données. La documentation de l'API PostgreSQL fournit aux développeurs des détails complets sur ce que l'API est, comment ils peuvent la connecter facilement avec leur application, et aussi les obstacles qu'ils peuvent rencontrer lors de l'utilisation de l'API et comment les surmonter.
Avantages d'une documentation claire des API
Améliore l'expérience des développeurs
Une excellente documentation des API facilite grandement la vie des développeurs. Elle explique clairement ce que fait l'API, comment elle fonctionne et comment l'utiliser - tout cela aide les développeurs à se mettre rapidement à niveau.
Au lieu de perdre du temps à essayer de comprendre les choses ou de rester bloqué, ils peuvent se concentrer sur la construction. Cela réduit la frustration, stimule la productivité et facilite même la collaboration avec les coéquipiers.
Réduit la courbe d'apprentissage
Une bonne documentation des API aide à réduire la courbe d'apprentissage pour les développeurs qui essaient d'utiliser l'API. Cela conduit à son tour à un intégration plus rapide, économise du temps et de l'argent, et encourage des taux d'adoption plus élevés.
Facile à maintenir
Une bonne documentation des API facilite la maintenance à la fois de l'API et de toute application utilisant l'API. Des documents à jour aident les développeurs à comprendre les changements, à corriger les bugs et à mettre à jour les fonctionnalités de leur application en toute confiance.
Fournit de la visibilité pour votre produit
Une bonne documentation des API augmente la visibilité de votre produit et encourage une utilisation fréquente en facilitant la compréhension et l'intégration par les développeurs. Elle favorise également l'intégration par des tiers, aidant votre produit à atteindre un public plus large.
Composants clés de la documentation des API
Il existe de nombreux composants qui constituent une bonne documentation des API. Dans cette section, nous allons parcourir un exemple concret de documentation des API bien préparée : l'API Web Spotify.
Aperçu/Description et utilisations de l'API
Il s'agit de la toute première étape dans la rédaction d'une bonne documentation des API. Cette section explique aux utilisateurs en quoi consiste l'API et contient également des informations sur le type de ressources qu'elle fournit.
La section d'aperçu est généralement courte, peut-être 3-4 phrases, et elle décrit ce que fait l'API, les ressources disponibles, ses points de terminaison et les méthodes attachées à chaque point de terminaison. Cela vous aide à vous mettre rapidement à jour pour savoir si cette API particulière fournit ce dont vous avez besoin pour compléter votre projet.
Comme vous pouvez le voir, la description de l'API Spotify explique comment elle vous aide à créer des applications qui "peuvent interagir avec le service de streaming de Spotify, comme la récupération de métadonnées de contenu, la création et la gestion de listes de lecture, ou le contrôle de la lecture."
Points de terminaison
Les points de terminaison sont un composant important dans la documentation des API. Les développeurs les utilisent pour communiquer avec d'autres serveurs. Ils sont également utilisés pour les transferts de données. Un point de terminaison est appelé le "point de contact" dans le canal de communication entre deux serveurs.
Lors de la documentation d'un point de terminaison, il est important de noter les différents composants des points de terminaison, car cela augmente la qualité de votre documentation des API. Les composants d'un point de terminaison incluent son nom, description, url, méthodes, paramètres, etc.
Par exemple, si vous souhaitez obtenir les détails des artistes les plus écoutés d'un utilisateur, voici à quoi ressemble le point de terminaison :
GET https://api.spotify.com/v1/me/top/artists
Rappelez-vous, nous avons précédemment mentionné les composants clés qui constituent un point de terminaison d'API, tels que le nom, la description, l'URL et la méthode HTTP. Prenons l'URL du point de terminaison Spotify ci-dessus pour voir comment ces composants sont présentés :
Nom : Obtenir les artistes les plus écoutés de l'utilisateur
Description : Récupère les artistes les plus écoutés par l'utilisateur actuel.
Méthode :
GET
Ce point de terminaison démontre comment une API bien documentée fournit toutes les informations nécessaires dont un développeur a besoin pour comprendre et l'utiliser efficacement.
Réponse :
{
"rank": 1,
"name": "Eminem",
},
{
"rank": 2,
"name": "NF",
},
{
"rank": 3,
"name": "Adele",
},
Maintenant, le code ci-dessus indique la réponse que je devrais obtenir de ma requête initiale et elle est affichée au format JSON.
Autorisation et authentification :
L'autorisation et l'authentification sont des outils importants utilisés pour vérifier l'accès accordé aux données sensibles.
Les API reçoivent des milliers de réponses et gèrent d'énormes quantités de données. L'authentification et l'autorisation sont des moyens de garantir que les données de votre API et vos utilisateurs sont en sécurité et protégés des pirates.
Notez que l'authentification et l'autorisation sont deux concepts différents. L'authentification consiste principalement à vérifier l'identité de quelqu'un qui souhaite utiliser votre API. L'autorisation, en revanche, décrit le niveau d'accès qu'un utilisateur déjà vérifié possède lorsqu'il interagit avec l'API.
Il existe trois principaux types d'authentification d'API. Chaque type est utilisé à différents stades ou niveaux, mais dans certains scénarios, aucune authentification n'est utilisée du tout.
Authentification de base : Il s'agit du type d'authentification d'API généralement utilisé pour tester les API internes. Il n'est pas recommandé pour les API utilisées publiquement car il n'est pas entièrement sécurisé. Cette API envoie un nom d'utilisateur et un mot de passe avec chaque appel d'API effectué par le client.
Authentification par clé : Dans ce type d'authentification, le client génère et envoie une clé très longue. La clé d'API est une longue chaîne contenant des jetons d'autorisation uniques. Ce type d'authentification est plus sécurisé que l'authentification de base - mais si la clé est divulguée, n'importe qui peut accéder à l'API jusqu'à ce qu'elle soit révoquée. Note : Ce type d'authentification est utilisé pour les applications légères.
Authentification OAuth : OAuth est le type d'authentification basé sur des jetons le plus courant et le plus sécurisé. Dans ce type d'authentification, au lieu d'envoyer un nom d'utilisateur et un mot de passe, une autorisation est d'abord demandée, qui est approuvée par l'utilisateur. Après que l'utilisateur a approuvé la demande, un jeton est généré qui peut être utilisé pour faire une requête d'API. Cette méthode est sécurisée, et les jetons générés ont également une durée d'expiration.
Examinons un exemple de l'API Spotify.
Spotify utilise OAuth 2.0 pour l'authentification et le contrôle d'accès. Pour utiliser la plupart des points de terminaison de l'API Web de Spotify, vous devez d'abord authentifier votre application et obtenir la permission de l'utilisateur :
GET https://accounts.spotify.com/authorize
Voici les détails clés du point de terminaison d'autorisation :
Nom : Autorisation
Description : Initiation du flux OAuth 2.0 pour autoriser les utilisateurs et permettre à votre application d'accéder aux données Spotify en leur nom.
Méthode :
GET
Paramètres et en-têtes :
Les paramètres sont la partie variable d'une ressource et comprennent un nom, une valeur et une description. Certains paramètres sont requis et sont utilisés pour faire des appels d'API, tandis que d'autres sont simplement optionnels.
Lors de la rédaction d'une documentation d'API, vous devez lister tous les paramètres et descriptions à côté de chaque paramètre. Il est également bon de spécifier pourquoi un tel paramètre est nécessaire et d'indiquer s'il est requis ou optionnel dans la documentation.
Les en-têtes, en revanche, sont similaires aux paramètres. Ils ont des paires clé-valeur et sont utilisés pour envoyer des informations supplémentaires (métadonnées) sur une requête au serveur. Si des en-têtes sont utilisés dans votre API, il est important de les inclure lors de la documentation de l'API.
Comme vous pouvez le voir sur l'image ci-dessus, nous avons certains paramètres de corps et paramètres d'en-tête. Pour les paramètres de corps, il y a grant_type (qui est requis), code (également requis), et redirect_uri (également requis). Vous pouvez également voir qu'ils ont des descriptions de la valeur listée.
Pour les paramètres d'en-tête, nous avons Authorization (requis) et Content-Type (également requis), à nouveau avec des descriptions de leurs valeurs.
Codes de gestion des erreurs et guide de dépannage :
Les erreurs sont inévitables, elles se produiront toujours malgré toute la prudence que vous pouvez avoir. C'est pourquoi une bonne documentation d'API doit inclure des conseils pour aider les développeurs à se rétablir rapidement lorsque les choses tournent mal.
Votre documentation doit fournir une section qui :
Suggère des correctifs possibles ou des conseils de dépannage pour certaines erreurs spécifiques.
Inclut des codes de réponse d'erreur et des journaux d'exemple, qui aident au débogage.
En ce qui concerne les appels d'API, deux composants clés à comprendre sont la requête et la réponse. Lorsqu'un appel d'API est effectué, une requête est envoyée au serveur, et une réponse est retournée. Cette réponse inclut un code de statut et, le cas échéant, un code d'erreur, et les deux sont essentiels pour comprendre ce qui s'est passé pendant la requête.
Par exemple, il y a des situations où vous faites un appel d'API et la réponse que vous obtenez est un code 404, ce qui signifie que la requête que vous avez faite n'a pas été trouvée. Mais lorsque tout se passe bien, vous devriez voir un code 200, ce qui signifie que votre requête a réussi.
Voici à quoi ressemble cette section :
{
"error": {
"status": 404,
"message": "Not Found"
}
}
En documentant correctement ces codes de statut et d'erreur avec leurs explications, les développeurs peuvent facilement identifier les problèmes et prendre les mesures appropriées pour les résoudre.
Voici quelques codes de statut de réponse courants et leur signification :
Code de statut de réponse :
| Code de statut | Description |
| 200 | OK |
| 201 | Créé |
| 202 | Accepté |
| 400 | Mauvaise requête |
| 401 | Non autorisé |
| 403 | Interdit |
| 404 | Non trouvé |
| 500 | Erreur interne du serveur |
| 502 | Mauvaise passerelle |
| 503 | Service indisponible |
Le tableau ci-dessus montre certains des codes de statut de réponse les plus courants que vous rencontrerez lors de l'utilisation d'une API et leur description.
Meilleures pratiques pour rédiger une documentation concise des API
Voici quelques meilleures pratiques qui peuvent vous guider lors de la rédaction de la documentation des API :
Assurez-vous que les utilisateurs comprennent clairement ce qu'est l'API, comment ils peuvent l'utiliser et les limites d'utilisation de l'API.
Connaissez votre public cible et concentrez-vous sur ce dont ils ont le plus besoin pour commencer avec la documentation des API.
Restez toujours fidèle aux informations essentielles et utilisez un langage clair et cohérent.
Structurez correctement votre documentation et rendez-la standard.
Les exemples sont importants. Utilisez-les toujours dans votre documentation et assurez-vous de les expliquer clairement.
Évitez les répétitions dans votre documentation.
Documentez toujours vos codes d'erreur clairement. Il est recommandé de les mettre sous forme de tableau.
Fournissez toujours un lien vers des fichiers externalisés dans les situations où plus de détails sont nécessaires. Cela aide à garder votre documentation courte et précise.
Passez en revue et mettez régulièrement à jour la documentation.
Intégrez les commentaires des utilisateurs pour une amélioration continue.
Conclusion
La documentation des API est devenue un composant critique dans le paysage technologique d'aujourd'hui. Une documentation claire et concise n'est pas seulement utile - elle est essentielle. Elle détermine souvent si une API réussit dans l'écosystème technologique et si les développeurs peuvent pleinement exploiter son pouvoir.
C'est un appel à l'action pour les développeurs, les organisations et les rédacteurs techniques : donnez la priorité à une documentation d'API de haute qualité et bien structurée. La clarté de votre documentation impacte directement l'utilisabilité, l'adoption et le succès à long terme de votre produit dans l'industrie.