L'importance de la documentation API

Les API sont conçues pour être immédiatement utilisées. C'est pourquoi vous devez vous assurer que le client, ou consommateur, peut les implémenter rapidement et comprendre à quoi elles servent. Malheureusement, nombre d'API compliquent énormément cette implémentation, ce qui va à l'encontre de leur raison d'être. Lorsque vous concevez votre API, vous devez donc penser à fournir une documentation détaillée la concernant, afin de permettre à vos développeurs d'intégrer ou de débugger les connexions, mais aussi de transmettre les données nécessaires lorsqu'un utilisateur effectue un appel, surtout lorsque celui-ci n'aboutit pas.

Bien entendu, la documentation de votre API doit proposer à vos développeurs un corps de réponse bien rédigé et cohérent, à la fois facilement désérialisable, itérable et compréhensible. Toutefois, n'oubliez pas de mettre également à leur disposition des références rapides correspondant aux différents résultats de l'appel, notamment l'utilisation des codes d'état. En cas d'échec, vous devrez fournir des messages d'erreur descriptifs qui indiqueront au client les raisons de l'échec, mais aussi la manière d'y remédier.

Planification en amont de la documentation API

Lorsque vous envisagez de concevoir une API, vous devez aussi prendre en compte l'actualisation de la documentation s'y rapportant. C'est un aspect qu'il convient de ne pas négliger, car c'est sur lui que repose la facilité d'utilisation de la plupart des API publiques. Vous pensez peut-être que concevoir une documentation est une tâche rapide et facile. Il s'agit pourtant pour une majorité d'entreprises d'un des plus grands défis dans la maintenance de leur API.

La documentation joue un rôle déterminant dans le succès d'une API. En effet, plus les documents sont fiables et faciles à comprendre, plus il est aisé d'implémenter une API. En revanche, si les documents sont confus, obsolètes, incomplets ou trop alambiqués, le parcours sera tortueux et la frustration ainsi générée mènera souvent les développeurs à utiliser les solutions des concurrents.

Le défi réside dans la cohérence : votre documentation doit avoir une présentation homogène, mais aussi s'aligner sur les fonctionnalités de votre API tout en intégrant les dernières modifications. Votre documentation doit évidemment être facile à comprendre et rédigée à l'attention des développeurs, de préférence par une équipe spécialisée dans ce genre de tâches. Encore récemment, les solutions utilisées pour la documentation reposaient sur des systèmes tiers particulièrement onéreux, sur l'utilisation d'un SGC (système de gestion de contenu) existant ou encore sur un SGC dédié, basé sur un logiciel open source de type Drupal/WordPress. Pourtant, même si ces solutions coûteuses destinées à la documentation API apportent une cohérence en matière de présentation (une tâche plus difficile à réaliser avec un SGC), leur synchronisation dépend du travail manuel du développeur (si elle est basée sur le code) ou de l'équipe de documentation.

Mais aujourd'hui, grâce à la généralisation des spécifications ouvertes (comme le langage RAML) et des communautés associées, le processus de documentation se simplifie. Plutôt que d'analyser les commentaires en code et de consulter les descriptions en ligne généralement rédigées par les développeurs, l'équipe de documentation est capable de fournir des documents descriptifs au sein même de la spécification d'API. Tous les paramètres et exemples de code sont déjà inclus, ce qui facilite grandement la transition vers la documentation. Et avec la multiplication des entreprises SaaS (Software as a Service, logiciel en tant que service) de documentation API qui utilisent et développent ces spécifications, la création d'un portail d'API et d'une documentation efficaces est désormais à la fois simple et abordable. 

Comment bien rédiger la documentation API

Une bonne documentation doit pouvoir servir à la fois de référence et de support pédagogique : les développeurs vont y trouver rapidement les informations qu'ils cherchent et y apprendre comment intégrer la ressource ou méthode qui les intéresse.

Voilà pourquoi une bonne documentation se doit d'être claire, concise et visuellement attrayante. Et bien entendu, elle doit fournir les informations suivantes :

• Une explication claire du rôle de la méthode ou ressource
• Des repères indiquant aux développeurs les informations importantes, notamment les alertes et les erreurs
• Un exemple d'appel accompagné du corps de type de support associé
• Une liste des paramètres utilisés dans le cadre de cette ressource ou méthode, ainsi que les types, le formatage spécial, les règles et les cas d'utilisation correspondant
• Un exemple de réponse, incluant le corps de type de support
• Des exemples de code pour les différents langages avec tout le code nécessaire
• (par ex., cURL avec PHP, ainsi que des exemples pour Java, .Net, Ruby, etc.)
• Des exemples de SDK (kit de développement), s'ils sont fournis, montrant comment accéder à la ressource ou à la méthode en utilisant le SDK pour un langage donné
• Des expériences interactives d'essai ou de test des appels d'API (API Console, API Notebook)
• Une foire aux questions/scénarios fréquents avec des exemples de code
• Des liens vers des ressources supplémentaires (autres exemples, blogs, etc.)
• Une section de commentaires destinée aux utilisateurs et consacrée au partage de code et aux discussions s'y rapportant
• D'autres ressources de support (forums, formulaires de contact, etc.)

Outils dédiés à la documentation API

L'un des principaux avantages du développement axé sur les spécifications, c'est qu'il permet de dire adieu aux fournisseurs onéreux et complexes, tout comme aux solutions de documentation API ponctuelles basées sur un SGC de type WordPress ou Drupal. Grâce à des spécifications comme RAML, Swagger et API Blueprint, vous pouvez utiliser les outils de documentation prédéfinis proposés par leurs importantes communautés open source. Chacune offre un ensemble d'outils qui lui est propre, mais ici, nous avons choisi de nous concentrer sur les outils proposés par la communauté RAML. La communauté RAML a déjà mis en place des analyseurs adaptés aux différents langages, notamment Java, Ruby, PHP et Node. Elle propose aussi des scripts complets pour la gestion de la documentation API tout en offrant des environnements interactifs comme API Console et API Notebook. Ces outils vous permettent de réaliser votre documentation comme dans les exemples ReadMe.io, Constant Contact et Twilio ci-dessus, le tout avec un minimum d'efforts, si ce n'est l'installation et le choix de votre RAML. Vous trouverez ici un certain nombre d'outils en téléchargement gratuit.

Plus les entreprises prennent conscience de la valeur croissante des API, plus elles en développent. La possibilité de les publier de telle manière qu'elles soient faciles à trouver, à analyser et à comprendre par les développeurs est l'une des clés de voûte de la réussite de l'ensemble de votre programme d'API. Et une bonne documentation est nécessaire pour l'étayer.