Introduction aux API Web

Updated 03/04/2017 by Nicolas Bonnel

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 :