Introduction aux API Web
Le terme API existe depuis quelques temps, mais il est de plus en plus visible sur le Web. C'est dû en bonne partie au développement récent de l'automatisation et de la robotisation dans notre société. Cet article présente ce que sont les API Web et à quoi elles servent.
Présentation
API est l'acronyme de Application Programming Interface, ou interface de programmation applicative. C'est la liste des points d'entrée d'un programme informatique et ça permet en quelques sortes de le piloter. Il existe 2 types d'API qui correspondent à 2 manières d'interagir avec les programmes :
- Le programme est disponible sous forme de librairie : il devient alors sous-programme d'un programme principal qui l'appelle au travers de fonctions, classes, méthodes ...
- Le programme est disponible sous forme de service Web : le programme principal utilise ses fonctionnalités au travers d'appels HTTP distants. C'est cette approche que je vais développer dans cet article au travers du terme API.
Les API permettent donc aux programmes de communiquer entre eux. Dans les 2 cas il est crucial que les API soient bien documentées pour pouvoir être utilisées correctement et que les développeurs puissent faire les bons liens entre les programmes.
Intérêt
Le découpage de programmes informatiques en librairies ou services Web permet de les réutiliser. Cela évite aux développeurs de devoir réinventer la roue à chaque fois. De plus, certains traitements nécessitent d'importantes ressources de calcul. Les services Web permettent de mutualiser ces ressources en faisant tourner le programme sur un gros serveur.
On peut citer comme exemple les fonds de cartes à plusieurs niveaux de la planète : leur stockage et utilisation nécessite plusieurs centaines de gigaoctets d'espace disque et mémoire vive. Il est beaucoup plus simple et moins coûteux pour le développeur d'utiliser un service comme Google Maps ou OpenStreetMap.
Documentation
La documentation d'une API est un point crucial que l'on peut avoir tendance à sous estimer. Une API est faite pour être réutilisée, et sans manuel d'utilisation il est très difficile de bien comprendre comment s'en servir. Toutes les fonctionnalités non documentées sont donc considérées comme inexistantes.
Il existe plusieurs manières de documenter une API. On peut la décrire de manière verbeuse, avec par exemple un article rédigé. On peut aussi la décrire en suivant un formalisme, comme par exemple OpenApi (connu aussi en tant que Swagger), RAML, I/O Docs ou API Blueprint. L'avantage de cette deuxième approche est qu'il devient plus facile de faire des catalogues d'API, comme par exemple celui-ci ou celui-la
Les API Koumoul
Nous avons choisi de documenter nos API en suivant le nouveau formalisme OpenAPI 3.0. Nous avons développé une librairie et un service de visualisation qui sont tous les 2 en open source. Le service de visualisation est déployé à cette adresse et librement utilisable par n'importe qui.
Les documentations de nos services sont disponibles à ces adresse :