| Les deux révisions précédentes Révision précédente Prochaine révision | Révision précédente |
| technique:adminserv:etherpad:api [2020/11/08 22:30] – ↷ Page déplacée de technique:adminsys:etherpad:api à technique:adminserv:etherpad:api qduchemi | technique:adminserv:etherpad:api [2021/01/04 18:28] (Version actuelle) – qduchemi |
|---|
| ====== Utilisation de l'API d'Etherpad ====== | {{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]]. | 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 ===== | ### 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. | 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. |
| |
| Pour cette raison, il est **formellement interdit** d'utiliser l'API depuis l'extérieur de l'infrastructure tant que ce problème n'est pas réglé. | <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 : | L'API utilise une clé pour se connecter. On peut la récupérer en se rendant dans le conteneur, par exemple : |
| <code bash> | <code bash> |
| qduchemi@pica01:~$ docker exec -it etherpad-app 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> | </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. | Attention, opération définitive. Elle supprime en particulier l'ensemble des versions accessibles dans le timeslider. |
| |
| <code bash> | <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> | </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é. |