De plus en plus d’organisations tirent parti de la puissance des API pour optimiser leurs activités. Les API sont devenues un moyen de débloquer de la valeur et de fournir un service supplémentaire.
Malgré leur popularité générale, toutes les API ne sont pas des réussites. L’adoption et l’utilisation d’une API déterminent en grande partie son succès. Pour favoriser l’adoption, votre API doit être facile à trouver et à utiliser.
La meilleure façon d’y parvenir est de documenter votre API en détail. Il s’agit notamment de détailler les composants critiques afin de les rendre plus faciles à comprendre. Découvrez quelques-uns des composants que vous devez inclure dans la documentation de votre API.
Qu’est-ce que la documentation de l’API ?
La documentation de l’API est un contenu technique qui décrit une API en détail. Il s’agit d’un manuel contenant toutes les informations nécessaires pour travailler avec l’API. Le document couvre le cycle de vie de l’API et les instructions relatives à l’intégration et à l’utilisation de ses composants.
La documentation de l’API couvre les descriptions des ressources, les points d’extrémité, les méthodes, les demandes et les exemples de réponses. Elle peut également inclure des guides pratiques et des tutoriels montrant aux utilisateurs comment l’intégrer. L’exploration de chaque section permet aux utilisateurs d’acquérir une solide compréhension de l’intégration et de l’utilisation de l’API.
Les éditeurs tels que Google Docs étaient autrefois largement utilisés pour la documentation professionnelle sur les API. Aujourd’hui, il existe des outils plus avancés comme Document 360, Confluence et GitHub Pages. Ces outils permettent d’intégrer le texte et le code pour faciliter les flux de travail.
1. Vue d’ensemble et objectif de l’API
La première étape de la documentation d’une API consiste à faire savoir aux utilisateurs de quoi il s’agit. Incluez des informations sur le type de ressources qu’elle fournit. Les API renvoient généralement diverses ressources, afin que l’utilisateur puisse demander ce dont il a besoin.
La description est brève, généralement une à trois phrases qui décrivent la ressource. Décrivez la ressource disponible, les points d’accès et les méthodes associées à chaque point d’accès. En tant que développeur de l’API, vous êtes le mieux placé pour décrire ses composants, ses fonctionnalités et son cas d’utilisation.
Voici un exemple de description de l’API Airbnb :
2. Méthodes d’authentification et d’autorisation
Les API traitent des milliers de demandes et d’énormes quantités de données. L’authentification est l’un des moyens de garantir que les données de votre API et de vos utilisateurs sont protégées contre les pirates informatiques. L’authentification de l’API vérifie l’identité d’un utilisateur et lui donne accès aux ressources.
Il existe plusieurs façons d’assurer la sécurité des points d’extrémité. La plupart des API utilisent une clé API. Il s’agit d’une chaîne de caractères qu’un utilisateur peut générer à partir du site web et utiliser pour l’authentification.
La documentation de l’API doit guider les utilisateurs sur la manière d’authentifier et d’autoriser leurs identités. Le diagramme suivant présente les informations d’authentification de l’API de Twitter.
3. Points de terminaison, modèles d’URI et méthodes HTTP
Dans cette section, nous montrons comment accéder à la ressource. Les points de terminaison ne montrent que la fin du chemin, d’où leur nom. Ils indiquent l’accès à la ressource et les méthodes HTTP avec lesquelles le point de terminaison interagit, à savoir GET, POST ou DELETE.
Une ressource peut avoir plusieurs points d’accès. Chacun d’entre eux a un chemin d’accès et une méthode différents. Les points d’accès ont généralement une brève description de leur objectif et un modèle d’URL.
L’exemple de code suivant montre un point de terminaison GET utilisateur sur Instagram.
GET /me?fields={fields}&access_token={access-token}
4. Formats de requête et de réponse
Vous devez documenter les formats de requête et de réponse afin que l’utilisateur sache à quoi s’attendre. La requête est une URL d’un client demandant une ressource, tandis que la réponse est un retour d’information du serveur.
Voici un exemple de demande que vous pouvez envoyer à l’API LinkedIn.
GET https://api.linkedin.com/v2/{service}/1234
Et voici un exemple de réponse qu’elle peut renvoyer :
{
"id": 1234,
"relatedEntity": "urn:li:relatedEntity:6789"
}
5. Paramètres et en-têtes
Vous devez également documenter les paramètres de vos points de terminaison, qui sont des options que vous pouvez leur transmettre. Les paramètres peuvent être un identifiant ou un numéro qui spécifie la quantité ou le type de données renvoyées en réponse.
Il existe différents types de paramètres, notamment les paramètres d’en-tête, de chemin et de chaîne de requête. Les points de terminaison peuvent contenir différents types de paramètres.
Vous pouvez inclure certains paramètres dans les en-têtes de requête HTTP. En général, ces paramètres sont utilisés à des fins d’authentification, comme une clé d’API. Voici un exemple d’en-tête contenant des clés API :
headers: {
'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}
Les paramètres de chemin sont inclus dans le corps du point de terminaison, directement dans l’URL. Ils indiquent à l’utilisateur où et comment placer les paramètres et comment la réponse apparaîtra. Les mots entre accolades sont des paramètres.
Vous pouvez également utiliser des deux-points ou une autre syntaxe pour représenter les paramètres du chemin d’accès.
/service/myresource/user/{user}/bicycles/{bicycleId}
Avec les paramètres de requête, vous devez placer un point d’interrogation ( ?) avant la requête sur un point final. Séparez ensuite chaque paramètre par une esperluette (& ;). Microsoft dispose d’une bonne documentation sur l’API Graph.
6. Codes d’erreur et gestion des erreurs
Il arrive que des requêtes HTTP échouent, ce qui peut laisser l’utilisateur perplexe. Incluez les codes d’erreur attendus dans la documentation pour aider les utilisateurs à comprendre les erreurs.
LinkedIn fournit des codes d’erreur HTTP standard pour la gestion des erreurs :
7. Exemples de code
Les extraits de code sont des éléments essentiels de votre documentation. Ils montrent aux utilisateurs comment intégrer l’API dans différentes langues et différents formats. Incluez dans la documentation la manière d’installer et d’intégrer les SDK (kits de développement logiciel) dans différentes langues.
RapidAPI propose de bons exemples d’extraits de code pour les développeurs :
9. Versionnement de l’API et journaux des modifications
Le versionnement de l’API est un élément essentiel de la conception de l’API. Il garantit la fourniture de services ininterrompus à vos utilisateurs. Le versionnage permet d’améliorer l’API avec de nouvelles versions sans affecter les applications clientes.
Les utilisateurs peuvent continuer à utiliser les anciennes versions ou migrer vers des versions plus avancées en temps voulu. Si de nouvelles modifications sont apportées aux journaux, il convient de les inclure dans la documentation afin que les utilisateurs en soient informés.
L’API Microsoft Graph possède des journaux de modifications bien documentés :
10. Informations de contact pour l’assistance et les commentaires
Enfin, incluez dans la documentation des contacts importants pour l’assistance et le retour d’information. Les utilisateurs peuvent ainsi vous contacter pour vous signaler des erreurs et obtenir des informations sur la manière d’améliorer l’API.
La valeur de la documentation de l’API
Si vous créez une API à des fins commerciales, c’est la consommation qui détermine son succès. Et pour que les utilisateurs consomment votre API, ils doivent la comprendre.
La documentation donne vie à une API. Elle explique les composants en détail dans un langage simple qui vend sa valeur et son utilisation aux utilisateurs. Les utilisateurs consommeront volontiers votre API s’ils bénéficient d’une excellente expérience de développement.
Une bonne documentation contribue également à simplifier la maintenance et la mise à l’échelle de l’API. Les équipes qui travaillent avec l’API peuvent utiliser la documentation pour la gérer.