technique:adminserv:etherpad:api

Différences

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

Lien vers cette vue comparative

Les deux révisions précédentes Révision précédente
technique:adminserv:etherpad:api [2020/12/31 16:17] – qduchemitechnique:adminserv:etherpad:api [2021/01/04 18:28] (Version actuelle) – qduchemi
Ligne 1: Ligne 1:
 +{{indexmenu_n>10}}
  
 +## Utilisation de l'API d'Etherpad
 +
 +Cette page recense quelques cas d'utilisations de l'API d'Etherpad. Dans la mesure où l'API est sujette aux changements, on se référera à la [[https://etherpad.org/|documentation officielle]].
 +
 +### Prérequis
 +
 +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>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>
 +
 +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 :
 +
 +<code bash>
 +qduchemi@pica01:~$ docker exec -it etherpad-app bash
 +node@id:~$ cat /opt/etherpad-lite/APIKEY.txt
 +</code>
 +
 +Cette clé sera passée en paramètre de la requête, comme valeur du paramètre `apikey`.
 +
 +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.
 +
 +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.
 +
 +On utilise la route ''deletePad'', et le paramètre ''padID'' qui correspond au nom du pad. Exemple :
 +
 +<code bash>
 +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é.