Bookify the subject

subject/docker-updater/docker-api.md

@@ -1,23 +1,38 @@
 Utiliser l'API de Docker
 ========================
 
-Le Docker Engine expose une API REST sur le protocole HTTP. Comme première
-tentative, vous pouvez essayer de récupérer des informations générales avec un
-simple `curl` :
+Le Docker Engine expose une API REST sur le protocole HTTP. Le client `docker`
+utilise cette API pour communiquer avec le daemon. C'est aussi cette même API
+que `docker-compose` emploie. En fait n'importe quel programme peut en faire
+usage, c'est d'ailleurs très simple d'utilisation.
 
+Si vous n'avez jamais communiqué avec une API REST, voici un premier exemple
+pour récupérer des informations générales sur le daemon Docker avec un simple
+`curl` :
+
+<div lang="en-US">
 ```bash
 curl -s --unix-socket /var/run/docker.sock http://localhost/v1.38/info | jq .
 ```
+</div>
 
-On retrouve un objet JSON contenant des informations similaires à ce que l'on
-obtient avec un `docker info`.
+On utilise l'option `--unix-socket` de `curl` car on ne se connecte pas
+directement à un port, comme c'est le cas habituellement avec le protocole
+HTTP. Bien évidemment lorsque le daemon Docker se trouve sur une machine
+distante (dans le cas de Docker Desktop sur Windows et Mac), on utilise l'IP et
+le port de la machine distance.
+
+Le premier élément dans le chemin de l'URL (`/v1.38/`) correspond à la version
+de l'API que l'on souhaite utiliser. Celle-ci change dès que des
+fonctionnalités sont ajoutées, à l'occasion d'une nouvelle version. Il n'est
+généralement pas nécessaire de mettre à jour cette version dans les programmes
+que vous développez car l'API est rétro-compatible : les anciennes versions de
+l'API restent accessibles.
+
+La commande que l'on a lancé nous retourne un objet JSON contenant des
+informations similaires à ce que l'on obtient avec un `docker info`. L'avantage
+est ici de pouvoir effectuer un traitement programmatique de ces informations.
 
-Le premier élément dans le chemin de l'URL correspond à la version de l'API que
-l'on souhaite utiliser. Celle-ci change dès que des fonctionnalités sont
-ajoutées, à l'occasion d'une nouvelle version. Il n'est généralement pas
-nécessaire de mettre à jour cette version dans les programmes que vous
-développez car l'API est rétro-compatible : les anciennes versions de l'API
-restent accessibles.
 
 Pour réaliser cet exercice, vous pouvez utiliser le langage de votre choix, en
 utilisant des outils ou des bibliothèques cohérents avec l'objectif recherché :