API pour Ezmlm Services (beta - 2016-11)

Dernière mise à jour : 2017-08-30

Rédaction d'un début de spécifications pour les webservices REST de gestion de listes ezmlm.
Implémenté dans ezmlm-php.

• la racine du service dans cet exemple est http://tb.org/ezmlm.php , c'est un exemple fictif
• si un Header HTTP "Authorization" est présent et contient un jeton SSO valide, l'utilisateur sera identifié par ce jeton
• les mots-clefs pourront être traduits pour un accès en français ou en anglais au choix :
  • lists => listes
  • subscribers => abonnes
  • moderators => moderateurs
  • allowed => posteurs
  • threads => sujets
  • authors => auteurs
  • count => compte
  • messages => messages
  • next => suivant
  • previous => precedent
  • latest => derniers
  • start => debut
  • nb => nb
  • sort => tri
  • order => ordre
  • ...

Ressources

Les exemples d'URL suivis d'une coche (✓) signifient que la fonctionnalité est implémentée dans ezmlm-php.

listes

• GET http://tb.org/ezmlm.php/lists (lister les listes) ✓
• POST http://tb.org/ezmlm.php/lists (ajouter une liste - administrateurs seulement) ✓

• GET http://tb.org/ezmlm.php/lists/search (rechercher parmi les listes) ✓

• GET http://tb.org/ezmlm.php/lists/blabla (lire les informations d'une liste : date de création, nombre de messages, date du dernier message...) ✓
• PUT http://tb.org/ezmlm.php/lists/blabla (modifier une liste - administrateurs seulement) note: utile ?
• DELETE http://tb.org/ezmlm.php/lists/blabla (supprimer une liste - administrateurs seulement) ✓

• GET http://tb.org/ezmlm.php/lists/blabla/calendar (afficher le "calendrier" d'une liste) ✓

• GET http://tb.org/ezmlm.php/lists/blabla/options (lire la configuration d'une liste - administrateurs seulement)
• PUT http://tb.org/ezmlm.php/lists/blabla/options (modifier la configuration d'une liste - administrateurs seulement)

• GET http://tb.org/ezmlm.php/lists/blabla/subscribers (lister les abonnés d'une liste) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/subscribers?count (compter les abonnés d'une liste) ✓
• POST http://tb.org/ezmlm.php/lists/blabla/subscribers (ajouter un abonné à une liste) ✓
• DELETE http://tb.org/ezmlm.php/lists/blabla/subscribers/jean@tela-botanica.org (désabonner quelqu'un d'une liste) ✓

• GET http://tb.org/ezmlm.php/lists/blabla/allowed (lister les posteurs autorisés d'une liste) ✓
• POST http://tb.org/ezmlm.php/lists/blabla/allowed (ajouter un posteur autorisé à une liste) ✓
• DELETE http://tb.org/ezmlm.php/lists/blabla/allowed/jean@tela-botanica.org (révoquer un posteur autorisé d'une liste) ✓

• GET http://tb.org/ezmlm.php/lists/blabla/moderators (lister les modérateurs d'une liste) ✓
• POST http://tb.org/ezmlm.php/lists/blabla/moderators (ajouter un modérateur à une liste) ✓
• DELETE http://tb.org/ezmlm.php/lists/blabla/moderators/jean@tela-botanica.org (révoquer un modérateur d'une liste) ✓

messages

• GET http://tb.org/ezmlm.php/lists/blabla/messages (lister les messages d'une liste) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages?contents=true (lister les messages d'une liste et inclure leur contenu) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages?contents=abstract (lister les messages d'une liste et inclure la première ligne de leur contenu) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages?count (compter les messages d'une liste) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages/latest (obtenir les derniers messages d'une liste - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages/latest/7 (obtenir les 7 derniers messages d'une liste - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages/513 (obtenir le message n°513 de la liste) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages/513?contents=false (obtenir le message n°513 de la liste, sans son contenu (métadonnées seulement)) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages/513/previous (obtenir le message de la liste précédant le n°513 - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages/513/next (obtenir le message de la liste suivant le n°513 - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/messages/513/attachments/mon_super_fichier.pdf (obtenir la pièce jointe "mon_super_fichier.pdf" du message n°513) ✓

• DELETE http://tb.org/ezmlm.php/lists/blabla/messages/513 (supprimer le message n°513 de la liste - administrateurs seulement)

• POST http://tb.org/ezmlm.php/lists/blabla/messages (poster un message sur la liste)

• GET http://tb.org/ezmlm.php/lists/blabla/messages/search (rechercher parmi les messages de la liste) ✓

sujets

• GET http://tb.org/ezmlm.php/lists/blabla/threads/ (lister les sujets d'une liste) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads?count (compter les sujets d'une liste) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/latest (obtenir les derniers sujets d'une liste) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/latest/4 (obtenir les 4 les derniers sujets d'une liste) ✓

• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet (lire les informations d'un sujet) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages (lister les messages d'un sujet - accepte le paramètre "contents")) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages?count (compter les messages d'un sujet)) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages/latest (obtenir le dernier message d'un sujet - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages/latest/7 (obtenir les 7 derniers messages d'un sujet - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages/513 (obtenir le message n°513 de la liste, dans le contexte de ce sujet - pour /next et /previous notamment - accepte le paramètre "contents")) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages/513/previous (obtenir le message précédant le n°513 dans le sujet - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages/513/next (obtenir le message suivant le n°513 dans le sujet - accepte le paramètre "contents") ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages/513/attachments/mon_super_fichier.pdf (obtenir la pièce jointe "mon_super_fichier.pdf" du message n°513) ✓

• POST http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages (poster un message sur la liste, dans le sujet)

• GET http://tb.org/ezmlm.php/lists/blabla/threads/search (rechercher parmi les sujets)) ✓
• GET http://tb.org/ezmlm.php/lists/blabla/threads/monsujet/messages/search (rechercher parmi les messages du sujet)) ✓

utilisateurs dans le contexte d'une liste

• GET http://tb.org/ezmlm.php/lists/blabla/users (lister les "utilisateurs" réels d'une liste, càd ayant posté au moins un message dans la liste)

• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org (lire les statistiques d'un auteur sur une liste : statut [abonné, modérateur...], droits, nombre de messages, date du dernier message...)

• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/threads (lister les sujets d'un auteur)
• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/threads?count (compter les sujets d'un auteur)
• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/threads/latest (obtenir le dernier sujets d'un auteur)
• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/threads/latest/7 (obtenir les 7 derniers sujets d'un auteur)

• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/messages (lister les messages d'un auteur - accepte le paramètre "contents")
• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/messages?count (compter les messages d'un auteur)
• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/messages/latest (obtenir le dernier message d'un auteur - accepte le paramètre "contents")
• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/messages/latest/7 (obtenir les 7 derniers messages d'un auteur - accepte le paramètre "contents")

• POST http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/messages (poster un message sur la liste, à la place d'un auteur - admins seulement)

• GET http://tb.org/ezmlm.php/lists/blabla/users/jean@tela-botanica.org/messages/search (rechercher parmi les messages d'un auteur)

utilisateurs

• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org (lire les statistiques d'un utilisateur => ?)
• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org/moderator-of/ (liste des listes dont l'utilisateur est modérateur) ✓
• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org/moderator-of/super-list (true si l'utilisateur est modérateur de super-list) ✓
• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org/subscriber-of/ (liste des listes auxquelles l'utilisateur est abonné) ✓
• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org/subscriber-of/super-list (true si l'utilisateur est abonné à super-list) ✓
• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org/allowed-in/ (liste des listes auxquelles l'utilisateur est autorisé à écrire) ✓
• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org/allowed-in/super-list (true l'utilisateur est autorisé à écrire à super-list) ✓
• GET http://tb.org/ezmlm.php/users/jean@tela-botanica.org/change-address-to/jean.dupont@tela-botanica.org (désabonner la première adresse de toutes les listes, et abonner à la place la seconde adresse) ✓

Paramètres de recherche et de tri

Les URL se terminant par /search acceptent les paramètres suivants :

• author
• min_date
• max_date
• date
• thread
• contents

Pour la recherche de sujets (threads), s'ajoutent les paramètres suivants :

• first_author
• last_author
• first_message_date
• last_message_date
• nb_messages

Tri et pagination des résultats

Toutes les URL GET retournant des listes acceptent les paramètres suivants :

• start : la liste commence à partir de ce message (offset)
• nb : la liste contiendra le nombre de messages demandé (count)
• sort : la liste sera triée selon le paramètre fourni (voir ci-dessus "Paramètres de recherche et de tri")
• order : le tri sera ascendent (asc) ou descendent (desc)

Format de sortie

Format de retour :
{
... à compléter ...
}

Permissions

L'utilisateur qui appelle le service sera identifié s'il fournit un jeton SSO valide; sinon il sera considéré comme anonyme.

Système de droits moderne (>= 2017-01)

Ce système remplace le système de droits historique, mais ce dernier continue à fonctionner.
Le SSO fournit maintenant des permissions (rôles) réglables depuis le site Web (Wordpress).
Par défaut, les utilisateurs fournissant un jeton portant le rôle "tb_ezmlm-php_admin" sont administrateurs de l'application (configurable dans config/config.json).

Système de droits historique (< 2017-01)

Sont administrateurs les utilisateurs fournissant un jeton dont l'adresse email est présente dans la liste des administrateurs, dans config/config.json (adapters => AuthProxyTB => admins).
Pour utiliser un jeton administrateur longue durée forgé par l'annuaire, ajouter sso-admin@tela-botanica.org à la liste des administrateurs.

---