10 composants importants de la documentation de l'API

De plus en plus d'organisations tirent parti de la puissance des API pour optimiser leur activité. Les API sont devenues un moyen de libérer de la valeur et de fournir un service supplémentaire.

Malgré leur popularité générale, toutes les API ne sont pas un succès. L'adoption et l'utilisation d'une API déterminent en grande partie son succès. Pour augmenter l'adoption, votre API doit être facile à trouver et à utiliser.

La meilleure façon de le faire est de documenter votre API en détail. Cela inclut le détail des composants critiques pour les rendre plus faciles à comprendre. Découvrez certains des composants que vous devez inclure dans la documentation de votre API.

Qu'est-ce que la documentation API?

La documentation de l'API est un contenu technique qui décrit une API en détail. C'est un manuel contenant toutes les informations nécessaires pour travailler avec l'API. Le document couvre le cycle de vie de l'API et des instructions sur l'intégration et l'utilisation de ses composants.

La documentation de l'API couvre les descriptions des ressources, les points de terminaison, les méthodes, les requêtes et les exemples de réponse. Il peut également inclure des guides pratiques et des tutoriels montrant aux utilisateurs comment l'intégrer. L'exploration de chaque section donne aux utilisateurs une solide compréhension de l'intégration et de l'utilisation de l'API.

Des éditeurs comme Google Docs étaient autrefois largement utilisés pour la documentation professionnelle des API. De nos jours, il existe des outils plus avancés comme Document 360, Confluence et GitHub Pages. Ces outils aident à intégrer du texte et du code pour faciliter les flux de travail.

1. Présentation 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. Inclure des informations sur le type de ressources qu'il fournit. Les API ont généralement diverses ressources qu'elles renvoient, de sorte que l'utilisateur peut 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 de terminaison et les méthodes attachées à chaque point de terminaison. En tant que développeur d'API, vous décrivez au mieux 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 gèrent des milliers de requêtes 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 les utilisateurs sont à l'abri des pirates. L'authentification API vérifie l'identité d'un utilisateur et leur donne accès à des ressources.

Il existe plusieurs façons de s'assurer sécurité des terminaux. 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 façon d'authentifier et d'autoriser leurs identités. Le schéma suivant montre les informations d'authentification de l'API Twitter.

3. Points de terminaison, modèles d'URI et méthodes HTTP

Dans cette section, montrez comment accéder à la ressource. Les points de terminaison n'affichent que la fin du chemin, d'où leur nom. Ils montrent l'accès à la ressource et Méthodes HTTP avec lequel le point de terminaison interagit, à savoir GET, POST ou DELETE.

Une ressource a probablement une variété de points de terminaison. Chacun avec un cheminement et une méthode différente. Les points de terminaison ont généralement de brèves descriptions de leur objectif et un modèle d'URL.

L'exemple de code suivant montre un point de terminaison utilisateur GET sur Instagram.

OBTENEZ /moi? champs={champs}&access_token={jeton d'accès}

4. Formats de demande et de réponse

Vous devez documenter les formats de demande et de réponse afin que l'utilisateur sache à quoi s'attendre. La demande est une URL d'un client demandant une ressource, tandis que la réponse est un retour du serveur.

Voici un exemple de demande que vous pouvez envoyer à l'API LinkedIn.

OBTENIR https://api.linkedin.com/v2/{service}/1234

Et voici un exemple de réponse qu'il 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 ID ou un nombre 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 en tant qu'en-têtes de requête HTTP. Habituellement, ceux-ci sont à des fins d'authentification comme une clé API. Voici un exemple d'en-tête avec des clés API :

en-têtes: {
 'Clé API X-Rapid': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
 'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}

Vous incluez les paramètres de chemin dans le corps du point de terminaison directement sur l'URL. Ils montrent à un utilisateur comment et où placer les paramètres et comment la réponse apparaîtra. Les mots entre accolades sont des paramètres.

Vous pouvez également utiliser les deux-points ou une autre syntaxe pour représenter les paramètres de chemin.

/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 de terminaison. Séparez ensuite chaque paramètre par une esperluette (&). Microsoft a une bonne documentation sur l'API Graph.

6. Codes d'erreur et gestion des erreurs

Parfois, les requêtes HTTP échouent, ce qui peut laisser un utilisateur confus. Inclure 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 d'extraits 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érents langages et formats. Incluez comment installer et intégrer des SDK (kits de développement logiciel) dans différentes langues dans la documentation.

RapidAPI propose de bons exemples d'extraits de code pour les développeurs :

9. Gestion des versions de l'API et journaux des modifications

La gestion des versions d'API est une partie essentielle de la Conception d'API. Il assure la fourniture de services ininterrompus à vos utilisateurs. La gestion des versions peut améliorer l'API avec de nouvelles versions sans affecter les applications clientes.

Les utilisateurs peuvent continuer à utiliser des versions plus anciennes ou migrer vers des versions avancées à temps. Si de nouvelles modifications sont apportées aux journaux, incluez-les dans la documentation afin que les utilisateurs en soient informés.

L'API Microsoft Graph dispose de journaux de modifications bien documentés :

Enfin, incluez les contacts importants dans la documentation pour obtenir de l'aide et des commentaires. Ceux-ci garantissent que les utilisateurs peuvent vous contacter avec des rapports d'erreur et des informations sur la façon d'améliorer l'API.

La valeur de la documentation de l'API

Si vous créez une API à valeur commerciale, la consommation détermine son succès. Et pour que les utilisateurs consomment votre API, ils doivent la comprendre.

La documentation donne vie à une API. Il explique les composants en détail dans un langage simple qui vend sa valeur et son utilisation aux utilisateurs. Les utilisateurs utiliseront volontiers votre API s'ils ont une excellente expérience de développeur.

Une bonne documentation permet également de simplifier la maintenance et la mise à l'échelle de l'API. Les équipes travaillant avec l'API peuvent utiliser la documentation pour la gérer.