• 6 heures
  • Moyenne

Ce cours est visible gratuitement en ligne.

course.header.alt.is_video

course.header.alt.is_certifying

J'ai tout compris !

Mis à jour le 04/03/2022

Écrivez la documentation de votre API

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

Dans le chapitre précédent, nous avons vu comment utiliser Git pour faire de bons commits, créer un README qui reflète bien votre projet, et utiliser Read the Docs pour publier votre documentation.

Dans ce chapitre, nous allons voir ensemble comment écrire de la documentation pour un cas particulier : une API.

Écrivez la documentation de votre API

Le but des API est d'être utilisée par de nombreux développeurs, souvent même extérieurs à votre projet ou entreprise. Dans ce contexte, une documentation accessible et facilement exploitable est une condition préalable au développement des API. Il est important d’avoir une documentation toujours à jour quand le code/les fonctionnalités de l’API évoluent.

C’est d’autant plus important quand le modèle de développement est centré sur le travail collaboratif, que ce soit au sein de l’entreprise (privé) ou bien dans le monde open source (public). En d’autres termes, synchronisez toujours les changements sur l’API et la documentation associée !

Que doit contenir votre documentation d'API ?

À titre d’exemple, regardez la documentation de l’API de Dropbox que vous connaissez certainement. On y trouve tous les éléments requis : les endpoints (HTTP reference, l’authentification), les exemples de code et les paramètres (API Explorer), le changelog (pour les changements depuis les versions antérieures).

Le cycle de vie d’une documentation d’API

Comme dans tout travail de conception, la documentation d’une API suit un cycle de vie particulier :

  1. La création : grâce aux outils en ligne, on peut facilement partager avec nos clients ou nos collègues la structure de l’API pour recueillir leur feedback et les demandes d’évolution des fonctionnalités, avant même de les coder.

  2. Le test : on peut facilement évaluer la cohérence des réponses des endpoints de l’API via des formulaires.

  3. Le partage de la documentation : en liant son repository Git avec la documentation, on  permet une totale synchronisation au sein de l’équipe. Ainsi, la documentation vit à côté du code, ce qui représente un avantage indéniable aujourd’hui. Enfin, l’équipe peut se mettre d’accord sur les règles syntaxiques et sémantiques métier à respecter en écrivant la documentation, afin d’assurer sa cohérence.  

Publiez votre documentation avec Apiary

Sans vouloir passer trop de temps sur l’outil, je vous propose de voir les différentes bonnes pratiques qu’Apiary propose dans le cycle de vie de la documentation.

Apiary propose un workflow qui respecte le cycle d'une documentation d'API, que nous avons vue à la section précédente. Voyons ensemble les points essentiels.

Créez votre documentation avec Apiary

À la création d’une nouvelle API, Apiary propose une visualisation en 2 parties. À gauche, un template de documentation d’API publique (sans authentification) générique, et à droite le live preview qui permet de visualiser en temps réel les modifications que vous apportez.

Interface de documentation d'API sur Apiary
Interface de documentation d'API sur Apiary

Regardons plus en détail le code à gauche.

Cette interface propose un code prérempli avec quelques éléments :

  • le type de format possible pour décrire l’API (Apiary permet de le faire en JSON ou en Markdown, par exemple) ;

  • le type d’hébergement pour l’API. Apiary propose 3 types d’hébergement ;

  • un titre rapide ainsi qu’une description ;

  • les éléments pour interroger les endpoints GET et POST de l’API.

FORMAT: 1A
HOST: https://polls.apiblueprint.org/
# Polls
Polls is a simple API allowing consumers to take part in polls and view their results.
## Questions Collection [/questions]
### List All Questions [GET]
+ Response 200 (application/json)
[
{
"question": "Favourite programming language?",
"published_at": "2015-08-05T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"votes": 2048
}, {
"choice": "Python",
"votes": 1024
}, {
"choice": "Objective-C",
"votes": 512
}, {
"choice": "Ruby",
"votes": 256
}
]
}
]
### Create a New Question [POST]
You may create your own questions using this action. It takes a JSON
object containing a question and a collection of answers (called “choices”)
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}
+ Response 201 (application/json)
+ Headers
Location: /questions/2
+ Body
{
"question": "Favourite programming language?",
"published_at": "2015-08-05T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"votes": 0
}, {
"choice": "Python",
"votes": 0
}, {
"choice": "Objective-C",
"votes": 0
}, {
"choice": "Ruby",
"votes": 0
}
]
}

Je vous recommande de compléter ce premier template grâce aux éléments dont vous avez besoin (authentification, paramètres, etc.), pour voir les changements directement dans le live preview.

Testez votre documentation avec Apiary

Une fois la documentation créée, la phase suivante du cycle consiste à la tester pour évaluer si elle correspond bien aux usages envisagés.

Apiary propose cette possibilité de manière native, ce qui est très pratique. L’interface permet de tester les endpoints de l’API en utilisant un formulaire avancé. Cette option est accessible directement depuis l’éditeur d’Apiary.

Testez les endpoints avec Apiary
Testez les endpoints avec Apiary

Collaborez autour de votre documentation avec Apiary 

La fonctionnalité que je préfère avec Apiary, c’est la facilité avec laquelle on peut synchroniser sa documentation d’API avec un repository Git public en quelques clics.

Une fois la synchronisation effectuée, l’éditeur d’Apiary change légèrement d’apparence. Il laisse apparaître un bouton “Push” en haut à droite, qui vous permet de commiter vos changements, et un bouton “Branch: master” qui vous indique dans quelle branche de votre code vous vous trouvez.

Partagez votre API avec Apiary
Partagez votre API avec Apiary

Ici, vous pouvez voir apparaître en haut à droite une infobox pour le commit à venir.

Le repo Github avec l'API qui s'y est ajoutée automatiquement
Le repo GitHub avec l'API qui s'y est ajoutée automatiquement

On retrouve maintenant le fichier de la documentation directement dans le repository. Ainsi, Apiary propose une intégration complète dans Git pour favoriser le travail d’équipe.

En résumé

Dans ce chapitre, nous avons vu que :

  • la documentation de votre API est cruciale pour assurer un partage au sein de votre équipe ou pour des utilisateurs potentiels ;

  • elle devrait comporter :

    • la manière de s'authentifier s’il s’agit d'une API privée,

    • la définition des endpoints,

    • les paramètres éventuels,

    • quelques extraits de code,

    • des exemples de requêtes et de réponses ;

  • le cycle de vie de la documentation comprend la création, le test et le partage ;

  • Apiary est une plateforme qui permet notamment de gérer ce cycle pour vos API. Son intégration avec les workflows de Git fournit un outil très puissant pour améliorer la productivité de l’équipe. 

Voilà, nous sommes arrivés à la fin de la première partie de ce cours, dans laquelle nous avons abordé les grandes lignes pour écrire une documentation qui permet une amélioration de la lisibilité et de l’évolutivité du code, mais également qui favorise le travail en équipe. 

Dans la seconde partie de ce cours, je vous propose de voir comment écrire la documentation technique de vos projets.

Exemple de certificat de réussite
Exemple de certificat de réussite