Documentation API : Comment l’écrire et les Exemples

Lorsque vous achetez un nouveau produit, il est accompagné d’un manuel qui vous explique comment l’utiliser. Vous ne rentrerez jamais chez vous et ne déballez pas votre nouvelle console de jeu sans un manuel d’installation, d’utilisation et d’entretien.

Lorsque les clients ne savent pas comment utiliser les produits, ils sont moins susceptibles d’être retenus par l’entreprise ou d’acheter d’autres produits à l’avenir.

Une API (interface de programmation d’application) n’est pas différente. Lorsque des développeurs apprennent à utiliser une API, ils ont besoin d’un ensemble d’instructions pour réussir. Plutôt que d’être confronté à une multitude de billets soumis à votre équipe d’assistance, la documentation offre une interface entre votre entreprise et les utilisateurs finaux.

Les fournisseurs d’API sont tenus de fournir une documentation API pertinente, spécifique et actualisée, en phase avec les dernières évolutions de votre produit. Peu importe la qualité de votre API si les développeurs ne savent pas comment l’utiliser.

Qu’est-ce que la documentation API ?

La documentation de l’API est un ensemble d’instructions qui indiquent aux développeurs et aux autres parties intéressées comment utiliser votre API et ses services pour une fin spécifique. Il contient généralement des exemples de code, des tutoriels et des détails sur les fonctions, classes et types de retour. Il fournit aux développeurs toutes les informations dont ils ont besoin pour construire des intégrations avec l’API et faire des appels API avec le logiciel.

Les appels d’API sont un type de requête effectuée par le développeur tiers à l’API de la plateforme. Les appels d’API sont décrits dans la documentation et indiquent au développeur exactement ce qu’il peut demander à l’API de faire et comment.

La documentation de l’API explique clairement ses points de terminaison, interprète les raisons pour lesquelles vous souhaitez les utiliser et donne des exemples très précis de la manière dont vous souhaitez les utiliser.

Les API sont importantes car elles signifient que les développeurs n’ont pas à continuer à créer les mêmes solutions logicielles à partir de zéro. Les API permettent aux développeurs de tirer parti d’autres plateformes déjà créées et d’intégrer leurs fonctionnalités dans leurs propres programmes. De nombreuses grandes plateformes disposent d’API, notamment Twitter et GitHub.

Types d’API

Pour l’équipe

Vous disposez peut-être d’une API interne à votre entreprise et destinée à être utilisée uniquement par les membres de votre équipe. L’objectif de ce type d’API serait de rationaliser le transfert de données entre les équipes et les systèmes. Les développeurs internes de votre entreprise sont donc ceux qui seraient responsables de l’utilisation de cette API.

Pour les partenaires

Les API partenaires sont partagées en dehors de l’organisation, mais uniquement avec ceux qui ont une relation commerciale avec l’entreprise qui fournit l’API. Seuls les clients autorisés ont accès à l’API et, par conséquent, les mesures de sécurité ont tendance à être plus strictes avec ce type d’API.

Pour les utilisateurs finaux

Les API pour les utilisateurs finaux ou les API ouvertes peuvent être utilisées par tout développeur sans aucune restriction. Ces types d’API n’ont pas d’authentification particulièrement stricte et les mesures d’autorisation parce que les fournisseurs veulent que l’API soit adoptée par autant de développeurs que possible. Parfois, ce type d’API sera disponible pour un abonnement qui est gradué selon le nombre d’appels API en cours.

Qui écrit la documentation API?

Naturellement, comme ce sont les développeurs qui construisent les API, ils sont souvent chargés de rédiger la documentation. Malheureusement, la documentation rédigée par les développeurs peut souvent être trop technique, car les développeurs sont très proches du sujet. La documentation rédigée par les développeurs peut également être laissée de côté, car les développeurs se concentrent en réalité sur la création et la maintenance de l’API.

Pour cette raison, de nombreuses entreprises emploient des rédacteurs techniques professionnels pour créer leur documentation API. Les rédacteurs techniques ont la capacité technique de comprendre l’API et les compétences créatives pour être en mesure d’ écrire du contenu engageant pour les utilisateurs finaux qui sont développeurs.

Les développeurs d’API fournissent au rédacteur technique les informations dont il a besoin pour documenter l’API avec précision. S’il manque des parties dans la documentation, les développeurs peuvent aider le rédacteur technique à les compléter, ce qui permet d’obtenir un document clair et accessible à son public cible.

Aussi, consultez notre article sur Comment créer une expérience magique de développeur API avec la documentation.

Avantages de la documentation de l’API

Pour les fournisseurs qui souhaitent proposer une API, le développement de la documentation peut avoir de nombreux avantages importants pour votre organisme.

Améliore l’expérience des développeurs de l’API

Avant tout, la documentation API améliore l’expérience des développeurs. Peu importe la qualité de votre API est si les développeurs potentiels ne comprennent pas comment l’utiliser. Une bonne documentation d’ API aide les développeurs à comprendre les différents terminaux qu’il a à offrir et les exemples de cas d’utilisation particuliers. Lorsque vous améliorez l’expérience de développeur que vous augmentez le nombre d’utilisateurs potentiels que vous pouvez attirer vers votre produit.

Réduit le temps passé à intégrer des développeurs internes ou des partenaires externes
Une bonne documentation API signifie que vos équipes de support et de succès doivent passer moins de temps à intégrer de nouveaux internes développeurs ou partenaires externes. Les nouveaux utilisateurs de votre API ont toutes les informations dont ils ont besoin pour commencer avec votre plateforme et se mettre en place pour réussir. Lorsque les processus sont documentés, cela supprime le besoin pour que des membres particuliers de l’équipe interviennent.

Maintenance du produit efficace et mises à jour plus rapides

Lorsque vous documentez efficacement votre API, cela signifie que vous pouvez gérer l’entretien de votre produit et le mettre à jour plus rapidement. Avec la documentation de l’API, vous savez exactement ce que votre produit doit faire et comment il est censé aider les utilisateurs finaux. La documentation vous donne une vue plus intime de l’API et vous permet de déployer plus rapidement les mises à jour qui seront adoptées par les utilisateurs.

Aide les utilisateurs internes et externes à comprendre l’API et ses capacités

L’un des principaux avantages de la documentation API est qu’elle aide les utilisateurs internes et externes à comprendre l’API, à quoi elle peut servir et comment vous pouvez la déployer à vos propres fins. Si vous n’expliquez pas les capacités potentielles de l’API, les nouveaux utilisateurs ne sauront pas comment l’utiliser et l’adoption du produit sera lente. Les utilisateurs potentiels d’une API utilisent la documentation pour prendre la décision d’utiliser ou non votre produit.

La source de référence pour les membres de l’équipe en matière d’objectifs de l’API

Les membres de l’équipe interne de votre organisation peuvent se référer à la documentation de l’API lorsqu’ils veulent se familiariser avec les objectifs de votre API. Même ceux qui n’étaient pas directement impliqués dans la construction de l’API ou écrire la documentation comprendra le but de l’API et sera en mesure de soutenir le travail de l’équipe de développement de l’API.

Permet d’identifier rapidement les bugs et les problèmes

Lorsque vous documentez l’API, cela vous permet d’identifier rapidement les bugs et les problèmes résultant de la vérification de l’API pour documenter toutes ses fonctionnalités. Si votre API ne fonctionne pas comme conçu, ce commentaire peut être transmis à l’API qui peut ensuite prendre des mesures pour résoudre tous les problèmes. Le résultat est une API plus professionnelle et plus efficace qui fonctionne comme prévu.

Un logiciel de base de connaissances intuitif pour ajouter facilement votre contenu et l’intégrer à n’importe quelle application. Essayez Document360 !

COMMENCER

La Structure de la Documentation de l’API – Conception et Fonction

Un aperçu

Le plan de votre documentation API est également appelé aperçu. Il contient un résumé de l’API et de son objectif, et peut informer les utilisateurs potentiels des avantages de l’utilisation de cette API par rapport à d’autres.

Tutoriels

Les tutoriels constituent la partie principale de l’API et leur objectif est d’enseigner aux utilisateurs le concept de l’API et comment l’utiliser efficacement. Ils contiennent généralement des guides étape par étape sur la façon d’intégrer l’API et de la faire fonctionner correctement.

Authentification

L’authentification est la façon dont le fournisseur conserve les données de l’API en toute sécurité pour les développeurs et les utilisateurs finaux, et donc il peut avoir plusieurs schémas d’authentification. La documentation de l’API explique chaque méthode d’authentification afin que les utilisateurs comprennent comment accéder à l’API.

Définition du point d’extrémité

Les définitions de terminaux de l’API sont le moment où l’API se connecte au programme logiciel. Le point à que l’API interagit avec un autre système est considérée comme le point de terminaison et peut inclure une URL du serveur ou le service.

Statut et codes d’erreur

Les codes d’état et d’erreur sont utilisés par les API pour informer les développeurs lorsque l’API ne fonctionne pas comme prévu, ainsi qu’une description de l’état ou de l’erreur. Ils peuvent contenir des instructions sur la manière de procéder et de résoudre les erreurs qu’ils rencontrent.

Exemples

Lorsque les utilisateurs comprennent le fonctionnement de l’API, il est bon de leur donner des exemples montrant des exemples réussis d’appels, de réponses, de gestion des erreurs et d’autres opérations qu’ils pourraient rencontrer lors de l’utilisation de l’API.

Glossaire

Au lieu d’expliquer chaque terme technique dans votre documentation, vous pouvez créer un lien vers un glossaire qui fournit des définitions pour les termes, les schémas et plus.

Comment écrire votre première documentation API

Reconnaître l’audience

Avant de commencer à créer n’importe quel type de documentation API vous devez vous assurer que vous comprenez bien ce qui est prévu public pour votre produit. Vous devez savoir exactement sur quels types d’utilisateurs vous voulez vous concentrer, les besoins spécifiques et la manière dont ils utiliseront votre documentation sur le terrain.

Il est important de se rappeler que votre audience potentielle pour votre documentation API peut généralement être divisée en deux groupes. La première est celle des développeurs qui interagissent avec l’API et l’utilisent activement, qui aura besoin de plus de documentation suivant les lignes de tutoriels et les exemples de code. Le deuxième public est composé de responsables techniques et de gestionnaires de produits qui évalueront l’API et comment elle s’aligne avec objectifs commerciaux.

Créer une carte de voyage utilisateur

Lorsque les utilisateurs interagissent avec votre documentation API, ils peuvent être dans l’une des nombreuses étapes de l’utilisateur Voyage. Les utilisateurs qui évaluent d’abord votre API auront besoin de documentation pour leur dire exactement ce que votre API peut faire et résoudre les problèmes qu’il résout, ainsi que les définitions de fonctions et de terminaux, et comment votre API est différente des autres fournisseurs.

Créer une carte de voyage utilisateur vous permet de répondre aux utilisateurs qui sont à différents stades et de fournir une meilleure expérience de développeur. Les développeurs seront supportés à chaque étape du chemin au lieu de se demander ce que votre API peut faire pour eux.

Commencer par les directives pour les scénarios courants

Il y a certaines des fonctions les plus courantes pour lesquelles votre API sera utilisée afin que vous puissiez créer des directives pour ces scénarios. Vous devez vous assurer de traiter les cas d’utilisation typiques de votre API pour que les nouveaux développeurs puissent comprendre comment utiliser correctement l’API. Chaque cas d’utilisation doit avoir une section séparée et inclure un exemple de message dans chaque message.

En fournissant des directives pour des scénarios courants, vos développeurs pourront démarrer sans avoir à se battre seuls. Il montre également aux développeurs ce dont votre API est capable et peut les persuader de choisir votre API par rapport aux autres.

Ajouter des exemples de code

L’ajout d’exemples de code à la documentation de votre API permet aux développeurs de commencer rapidement à tester votre API et de comprendre tout son potentiel. Chaque point de terminaison doit être accompagné de ses propres exemples de code afin que les développeurs puissent adapter le code pour répondre à leurs spécifications exactes et tester les fonctionnalités les plus importantes du point de terminaison.Les exemples de code montrent aux développeurs potentiels comment fonctionne votre API et leur permettent de démarrer facilement, car ils peuvent simplement copier et coller le code.Vous pouvez inclure des exemples de code dans tous les différents langages de programmation dans lesquels votre API est disponible.

Appeler les messages d’erreur et les codes d’état

Les messages d’erreur et les codes de statut devraient être inclus dans votre documentation car ils le disent à vos développeurs quand ils ont ou n’ont pas passé un appel API réussi. Chaque message ou code doit inclure un bref description de la raison pour laquelle il est affiché afin que les utilisateurs puissent comprendre ce qui se passe quand ils interagissent avec le système.

Les descriptions qui accompagnent les messages d’erreur doivent être construites dans le but de montrer aux utilisateurs comment résoudre les problèmes eux-mêmes. Ils devraient être détaillés et spécifiques pour que les utilisateurs puissent comprendre pourquoi le système renvoie une erreur.

Maintenir votre documentation

Après avoir publié votre documentation pour la première fois, vous devez vous assurer de la consulter régulièrement pour maintenir votre contenu à jour. Rien n’est plus rebutant pour les utilisateurs potentiels de votre API qu’une documentation incomplète ou inexacte. Sans maintenir une documentation efficace au fil du temps, les développeurs ne pourront pas utiliser votre API et vous constaterez une baisse de l’adoption. Chaque fois que vous effectuez une mise à jour ou publiez une nouvelle fonctionnalité, cela doit être reflété dans la documentation et être considéré comme un élément essentiel de la livraison de votre API.

Meilleures pratiques de la documentation de l’API

1. Adopter une langue claire

Lorsque vous rédigez la documentation de l’API, vous ne savez pas quel niveau d’expertise les utilisateurs de votre documentation auront. C’est pourquoi il est important d’utiliser une langue claire et simple que tout le monde peut comprendre.

2. Inclure la documentation de référence

La documentation de référence de l’API est une liste complète des objets et des méthodes exposés par l’API, ainsi qu’une description de la manière d’utiliser chacun d’eux.. Cela enseigne aux développeurs tout ce qui est disponible et comment il fonctionne.

3. Implémenter des exemples

Vous devez utiliser aussi souvent que possible des exemples de fonctionnement de votre API, que vous pouvez trouver dans n’importe quelle référence de votre documentation. Il peut s’agir de tout ce qui illustre le concept de l’API et aide les développeurs à démarrer avec leurs propres appels d’API.

4. Mettez quelqu’un en charge de la documentation

Vous avez besoin de quelqu’un dans votre équipe dont le travail est de superviser l’expérience des développeurs de votre documentation API. Il pourrait s’agir de tout leur travail s’il est un rédacteur technique ou une responsabilité à temps partiel s’il est également un développeur.

5. Couvrez les types et les sujets différents

Vous devez vous assurer que votre documentation API est complète et qu’elle couvre les références, les guides et les exemples. Si certains domaines manquent, vous utiliserez ces informations pour décider où concentrer vos efforts futurs.

6. Insérer la documentation dans les processus

Votre documentation et votre API doivent évoluer en tandem. Avec l’évolution de l’API, vient le développement de votre documentation, notamment en parallèle des nouvelles fonctionnalités. Automatisez autant que possible et gagnez du temps avec votre documentation.

7. Fournir des guides de démarrage rapide

Les guides de démarrage rapide sont le meilleur moyen d’embarquer de nouveaux développeurs avec votre API et de commencer à utiliser votre API. Ils contiennent des instructions sur la façon d’utiliser votre API ainsi que des échantillons de code qui rendent l’accès à votre API beaucoup plus facile.

Consultez également notre blog sur la liste de contrôle de la documentation de l’API.

Meilleurs exemples de documentation API

Voici quelques exemples de documentation API réelle que vous pouvez utiliser pour inspirer vos propres efforts.

GitHub API

L’API GitHub est une API REST que les développeurs peuvent utiliser pour se connecter à la plateforme GitHub, qui est un outil de développement collaboratif pour projets logiciels. GitHub offre une documentation de démarrage rapide complète pour aider les développeurs à maîtriser l ‘API et des sections détaillées pour chaque aspect de l’utilisation de l’API.

Documentation de l’API Twilio

‘API Twilio est une autre API REST que les développeurs peuvent utiliser pour se connecter à la plateforme Twilio, une plateforme d’engagement client qui permet aux entreprises de communiquer à grande échelle. La documentation comprend tout ce dont vous avez besoin pour intégrer Twilio, y compris l’authentification avec HTTP et le SDK.

Docs de l’API Dropbox

L’API Dropbox permet aux développeurs de créer des intégrations avec la plateforme de partage de documents Dropbox. Elle propose des composants prédéfinis qui aident les utilisateurs à intégrer des composants Dropbox, ainsi qu’une référence API pour la création d’applications et d’intégrations personnalisées. Elle propose également plusieurs SDK officiels pour les langages de programmation les plus populaires.

La conclusion

La simple construction d’une API ne suffit pas pour assurer l’adoption d’un produit – vous devez fournir une documentation API complète pour montrer à vos utilisateurs potentiels et actuels comment utiliser votre outil. Si personne ne comprend ce que votre API est censé faire, Personne ne sera motivé pour l’utiliser et vous perdrez de nombreux profits potentiels. Même si votre API est à but non lucratif, vous voudrez toujours maximiser le nombre d’utilisateurs auxquels vous exposez votre API.

Lors de la création de votre documentation API, pensez à vos utilisateurs potentiels et aux types de contenu qui seront les aider à tirer le meilleur parti de votre outil. Vous devez répondre à tous les cas d’utilisation les plus courants et anticiper les obstacles que vos utilisateurs sont les plus susceptibles de rencontrer lorsque vous essayez d’implémenter votre API.

Offrir une API est un excellent moyen d’étendre la fonctionnalité de votre produit et d’atteindre de grands groupes de nouveaux utilisateurs. La documentation est le pont entre votre API et les utilisateurs finaux qui utilisent votre API pour réaliser leur but.

Planifiez une démo avec l’un de nos experts pour plonger plus profondément dans Document360

Réservez une démo