Différences

Ci-dessous, les différences entre deux révisions de la page.

--- technique:adminserv:etherpad:api [2020/12/31 16:17] – qduchemi
+++ technique:adminserv:etherpad:api [2021/01/04 18:28] (Version actuelle) – qduchemi
@@ Ligne 7: / Ligne 7: @@
 ### Prérequis
-L'API utilise **uniquement** des requêtes GET, ce qui signifie que les paramètres, y compris critiques, sont passés en clair dans l'URL. Néanmoins, les paramètres sont chiffrés en HTTPS, ce qui ne devrait pas poser de soucis.
+Avant la version 1.8, l'API utilisait **uniquement** des requêtes GET.
+Depuis la version 1.8, l'API supporte indifféremment les requêtes GET et POST.
-<bootnote>En cas de doute, on pourra utiliser l'API depuis le conteneur.</bootnote>
+<bootnote>Une clé secrète étant passée en paramètre, on veillera à bien utiliser une URL HTTPS. Même si la redirection  HTTP → HTTPS est automatique, c'est trop tard si l'URL est interceptée.</bootnote>
-Pour autant, elle reste utile, par exemple pour supprimer des pads. En effet, la base de données étant de type clé-valeur, avec l'ensemble des révisions stockées, ce serait beaucoup trop complexe à faire à la main.
+L'API permet de créer et de supprimer des pads, ainsi que de gérer les accès aux pads. Chez Picasoft, nous n'utilisons pas les fonctionnalités de groupes, toute la partie permissions n'est donc pas utile. L'API peut en revanche être utile pour supprimer des pads. En effet, la base de données étant de type clé-valeur, avec l'ensemble des révisions stockées, ce serait beaucoup trop complexe à faire à la main.
 L'API utilise une clé pour se connecter. On peut la récupérer en se rendant dans le conteneur, par exemple :
@@ Ligne 17: / Ligne 18: @@
 <code bash>
 qduchemi@pica01:~$ docker exec -it etherpad-app bash
-node@id:~$ export APIKEY=$(cat /opt/etherpad-lite/APIKEY.txt)
+node@id:~$ cat /opt/etherpad-lite/APIKEY.txt
 </code>
-La variable ''APIKEY'' est désormais utilisable pour les opérations sur l'API. On la passera systématiquement en paramètre GET, comme valeur du paramètre ''apikey''.
+Cette clé sera passée en paramètre de la requête, comme valeur du paramètre `apikey`.
-Enfin, on pourra requêter l'URL ''localhost:8080'', puisque l'on est dans le conteneur, et que l'image Docker d'Etherpad [[https://gitlab.utc.fr/picasoft/projets/dockerfiles/blob/master/pica-etherpad/Dockerfile|expose le port 8080 en interne]].
+La version de l'API est renvoyée sur la route `/api`.
+L'API est documentée au format OpenAPI sur `/api/openapi.json`, et peut être explorée via [l'éditeur Swagger](https://editor.swagger.io/), par exemple.
-===== Suppression d'un pad =====
+L'usage de l'API peut alors se faire depuis le conteneur, via l'URL ''localhost:8080/api/<version>''. On pourra bien entendu requêter l'API depuis l'extérieur.
+<bootnote>Pour des tâches récurrentes, on pourra utiliser des [clients de l'API](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) disponibles dans divers langages de programmation.</bootnote>
+### Suppression d'un pad
 Attention, opération définitive. Elle supprime en particulier l'ensemble des versions accessibles dans le timeslider.
@@ Ligne 31: / Ligne 37: @@
 <code bash>
-node@id:~$ curl "localhost:8080/api/1/deletePad?apikey=$APIKEY&padID=<nom du pad à supprimer>"
+node@id:~$ curl "localhost:8080/api/<version>/deletePad?apikey=<CLE>&padID=<nom du pad à supprimer>"
 </code>
+Il est plus sûr d'encoder les paramètres si ceux-ci contiennent des caractères spéciaux. Exemple :
+<code bash>
+node@id:~$ curl "localhost:8080/api/<version>/deletePad?apikey=<CLE> --get --data-urlencode 'padID=<nom du pad à supprimer>'"
+</code>
+### Réponse
+L'API répond toujours avec un objet JSON de la forme :
+```json
+{
+  "code": number,
+  "message": string,
+  "data": obj
+}
+```
+Le code vaut 0 si tout s'est bien passé, sinon le message contiendra une explication sur ce qui s'est mal passé.