Fournir des explications claires et ludiques améliore l'expérience des développeurs qui utilisent une API. C'est tout l'objet de la documentation API. Des outils facilitent le travail d'élaboration de ce support pédagogique indispensable.
Qu'est-ce qu'une documentation API ?
Une documentation API est un mode d'emploi à destination des développeurs qui utilisent l'API. Tutoriel vidéo, exemples de code, FAQ ou encore guide par étape : la documentation fournit des ressources pédagogiques, pour permettre aux développeurs d'exploiter, facilement et rapidement, tout le potentiel de l'API.
Pourquoi la documentation API est importante ?
La documentation API explique à quoi sert l'API, et comment faire pour l'utiliser dans les meilleures conditions. La documentation joue donc un rôle à la fois marketing et commercial : elle promeut l'API, et permet à ses utilisateurs d'exploiter toutes ses fonctionnalités. Avec une bonne expérience utilisateur, les développeurs continuent d'utiliser l'API, et la recommandent.
La documentation est également importante pour fixer les règles d'utilisation de l'API, dans un enjeu de sécurité.
API publiques, API partenaires ou API composites pour une architecture de microservices : avec une bonne documentation, le recours au support est réduit. Le gain de temps est notable.
Comment bien rédiger sa documentation API ?
- Rédiger pour les utilisateurs
- Contextualiser l'API
- Structurer la documentation chronologiquement
- Expliquer les fondamentaux
- Inclure des ressources ludiques
- Indiquer les tarifs de l'API
- Mettre à jour la documentation
1 - Rédiger pour les utilisateurs
La documentation doit être facilement compréhensible par les utilisateurs de l'API. Or le niveau de compréhension varie d'un profil utilisateur à un autre, en fonction de l'expertise, de l'âge ou encore du domaine de compétences techniques. Déterminer la cible d'utilisateurs permet d'adapter le langage, et de choisir le type de supports pédagogiques pertinent. Certains préfèreront une documentation au format vidéo, d'autres comprendront mieux un guide au format texte illustré avec des captures d'écran, par exemple.
En introduction de la documentation API, il est d'usage d'informer les développeurs sur le niveau d'expertise requis pour comprendre la documentation. Illustrations :
- La documentation de l'API Maps JavaScript annonce que le tutoriel « convient aux personnes ayant un niveau de connaissance débutant ou intermédiaire en HTML et CSS, et quelques connaissances sur JavaScript » : le guide est conçu de manière à accompagner l'utilisateur novice pas à pas, avec des ressources très visuelles.
- La documentation sur l'API Graph pour Instagram nécessite de « consulter notre documentation sur l'API Graph pour Facebook pour découvrir son fonctionnement avant de continuer » : les utilisateurs sont prévenus qu'il faut préalablement se familiariser au fonctionnement de l'API Facebook pour comprendre la documentation de l'API Instagram.
2 - Contextualiser l'API
En introduction de la documentation, il est judicieux de rappeler à quoi sert l'API, quelles sont ses fonctionnalités spécifiques et pour quel type de logiciel l'utiliser. Rappeler le contexte est utile à deux égards :
- L'utilisateur est assuré d'être au bon endroit.
- Le bref descriptif, si besoin, finit de convaincre l'utilisateur. L'introduction en effet est rédigée de manière attractive, de manière à mettre en valeur les atouts de l'API.
3 - Structurer la documentation chronologiquement
Dérouler le fil depuis la première étape du parcours du développeur qui a l'intention d'utiliser l'API permet de n'oublier aucune explication importante dans la documentation. Qu'il s'agisse d'un format vidéo ou d'un guide écrit, se baser sur la chronologie facilite le travail de rédaction de la documentation, et améliore sa compréhension.
Il est intéressant, lorsque la documentation est volumineuse, de créer un sommaire qui permet de se rendre au chapitre requis sans avoir à parcourir l'intégralité des ressources.
4 - Expliquer les fondamentaux
- Authentification. Le développeur qui souhaite utiliser l'API doit s'authentifier. Cette étape doit être expliquée dans la documentation. Il faut décrire comment obtenir et utiliser la clé API, qui permet d'accéder aux données et aux fonctionnalités autorisées lors d'un API call.
- Limites d'utilisation. Les limites d'utilisation indiquent un nombre maximum de requêtes par période de temps. Cette indication est essentielle pour encadrer les modalités d'utilisation de l'API, à des fins de sécurité. La documentation d'une API, par ailleurs, inclut les règles et conditions d'utilisation auxquelles le développeur doit se conformer. Cela permet d'interdire l'utilisation de l'API au développeur qui ne respecte pas les termes du contrat.
- Démarrage rapide. Les développeurs doivent être en mesure de commencer à utiliser l'API immédiatement. Les plus expérimentés en effet n'ont pas besoin d'un accompagnement pas à pas. Un accès rapide aux différentes fonctionnalités est également apprécié par les développeurs, pour faciliter la navigation dans la documentation.
5 - Inclure des ressources ludiques
Un tutoriel vidéo, des captures d'écran de certaines étapes complexes, des FAQ, des exemples de code à copier-coller : la documentation doit être agréable à parcourir, et facile à comprendre. Inclure des ressources pédagogiques visuelles et ludiques favorise la mise en pratique.
Exemple de FAQ sur la signification et la résolution des codes d'erreurs de l'API Amazon SP :
6 - Indiquer les tarifs de l'API
La documentation de l'API inclut un onglet de tarification.
7 - Mettre à jour la documentation
Il faut veiller à mettre à jour la documentation API en temps réel, pour toujours fournir une excellente expérience utilisateur. Le format changelog, ou journal des modifications, est répandu pour présenter les mises à jour de manière claire. Résolution d'erreurs fréquentes, nouvelles fonctionnalités ou encore améliorations récentes sont visibles dès la page d'accueil de la documentation API.
Utiliser régulièrement des outils de test d'API est efficace pour identifier les mises à jour opportunes, en matière de performance et de sécurité.
Le guide pour comprendre les langages HTML et CSS.
Découvrez comment utiliser les langages HTML et CSS pour gérer votre site web efficacement.
- Balises HTML à connaître
- Mettre à jour un fichier CSS
- Les écueils à éviter
- Ressources pédagogiques
Télécharger
Tous les champs sont obligatoires.
Merci d'avoir soumis le formulaire
Cliquez sur le lien pour accéder au contenu en tout temps
Quels outils utiliser pour rédiger sa documentation API ?
Postman
Postman est une plateforme pour créer, tester et documenter des API. La documentation est générée automatiquement à mesure que l'API est créée et modifiée. Des fonctions collaboratives permettent d'enrichir et de corriger la documentation. Compter entre 0 et 49 $ par utilisateur et par mois.
Apiary
Apiary est une application web pour développer et documenter des API. L'application offre une fonctionnalité de rédaction automatique de la documentation, et l'enrichit de ressources ludiques pour faciliter la prise en main de l'API par les développeurs. Apiary fait partie d'Oracle Cloud.
Swagger
Swagger met à disposition une multitude d'outils open source pour créer des API et leur documentation. La documentation est conçue de manière interactive, afin de fournir une expérience utilisateur agréable aux développeurs. Swagger permet de maintenir la documentation toujours à jour, à mesure des évolutions de l'API.
Pour aller plus loin dans la gestion de site web, téléchargez le guide d'introduction aux langages HTML et CSS, ou découvrez le logiciel CMS gratuit de HubSpot.
