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 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.
Note:
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.
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 :
qduchemi@pica01:~$ docker exec -it etherpad-app bash node@id:~$ cat /opt/etherpad-lite/APIKEY.txt
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, 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.
Note:
Pour des tâches récurrentes, on pourra utiliser des clients de l'API disponibles dans divers langages de programmation.
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 :
node@id:~$ curl "localhost:8080/api/<version>/deletePad?apikey=<CLE>&padID=<nom du pad à supprimer>"
Il est plus sûr d’encoder les paramètres si ceux-ci contiennent des caractères spéciaux. Exemple :
node@id:~$ curl "localhost:8080/api/<version>/deletePad?apikey=<CLE> --get --data-urlencode 'padID=<nom du pad à supprimer>'"
Réponse
L’API répond toujours avec un objet JSON de la forme :
- snippet.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é.