myList
Serveis TIC
myList

Comparteix:

API del servei

Introducció

Per accedir al servei mylist.upc.edu des d'aplicacions o processos externs s'han facilitat la API del servei.

El servei de mylist.upc.edu està basat en el programari lliure "sympa", que proveeix una API basada en SOAP i que podreu consultar en detall al manual on-line de sympa: https://www.sympa.org/manual/soap,  Aquesta API permet realitzar un conjunt limitat de funcionalitats del sympa i que es descriuen al següent punt.

Per facilitar la vida dels usuaris del servei, hem desenvolupat una API alternativa per poder accedir a aquesta API fent servir el protocol HTTPS en comptes de SOAP. Aquesta API permet executar les mateixes funcions, però amb una única URL.

Aquestes APIs requereixen autenticació del client que serà un usuari i una contrasenya.

  • La creació de llistes les poden fer els perfils PAS, PDI Personal i genèrics d'aplicació. En el cas de fer servir un genèric d'aplicació, cal garantir que es reben les notificacions del sistema, ja sigui creant filtres a la bústia per reencaminar els avisos, o bé configurant algun altre propietari de la llista que no sigui genèric. 
  • La resta de funcions s'executaran amb els permisos que tingui aquest usuari al servei.

 

API SOAP

La URL del servei API SOAP de mylist.upc.edu és: https://mylist.upc.edu/sympasoap

Les funcions que podem accedir-hi via API SOAP són:

  • login : Es validaran les credencials (usuari i contrasenya)
  • casLogin : Verifica un tiquet de proxy CAS contra el servidor CAS. En el servei de mylist.upc.edu encara no està integrat el servei amb el CAS de la UPC.
  • authenticateAndRun : Útil per clients SOAP que no poden guardar cookies HTTP; podran proveir la cookie de sessió i la comanda a executar en una única crida.
  • authenticateRemoteAppAndRun : Equivalent a l'anterior, però en un context de "trusted applications".
  • lists : Proveeix el llistat de llistes (segons els permisos de l'usuari)
  • complexLists : El mateix que l'anterior, però proveeix una estructura més complexa per a cada llista.
  • info : Proveeix informació descriptiva per una llista.
  • which : Proveeix el llistat de subscripcions per a un usuari
  • complexWhich : El mateix que l'anterior, però proveeix una estructura més complexa per a cada llista.
  • amI : Indica si un usuari és membre d'una llista.
  • review : Llista els membres d'una llista.
  • subscribe : subscriu l'usuari amb el què s'ha connectat a l'API a una llista.
  • signoff : de-subscriu l'usuari amb el què s'ha connectat a l'API d'una llista.
  • add : (per usuaris administradors) afegeix un usuari a una llista
  • del :(per usuaris administradors) de-subscriu un usuari d'una llista.
  • createList : (per a usuaris amb permís de creació de llistes) crea una nova llista de distribució
  • closeList :(per usuaris administradors) tanca una llista.

API HTTP(s)

La URL de l'API HTTP(s) és https://mylist.upc.edu/api/user_api.php 

 

Les funcions que es proveeixen via HTTPs són més limitades, i pot anar creixent durant la vida del servei segons les necessitats de la Universitat. Actualment, les funcions que podem accedir-hi via API HTTP són les que llistem a continuació.

Amb cada funció es mostra quins són els paràmetres. Els paràmetres amb un asterisc (*) al costat són obligatoris, la resta són opcionals.

  • action=lists (username*, password*, topic, subtopic): Proveeix el llistat de llistes (segons els permisos de l'usuari)
  • action=which (username*, password*, email*): Proveeix el llistat de subscripcions per a un usuari.
  • action=review (username*, password*, listname*): Llista els membres d'una llista si és pública o ets el seu administrador..
  • action=info (username*, password*, listname*): Proveeix informació descriptiva per una llista.
  • action=closeList (username*, password*, listname*): (per usuaris administradors) tanca una llista.
  • action=add (username*, password*, listname*, email*, gecos, quiet): (per usuaris administradors) afegeix un usuari a una llista
  • action=del (username*, password*, listname*, email*, quiet*): (per usuaris administradors) anul·la la subscripció un usuari d'una llista.
  • action=createList (username*, password*, listname*, subject*, template*, description*, topic*): (per a usuaris amb permís de creació de llistes) crea una nova llista de distribució


on tenim que aquests dos paràmetres:
    - username: Email de la persona que sol·licita l'acció
    - mail:         Email del membre de la llista

    - template: Hi ha 6 noms de template disponibles per crear llistes

      10_llista_publica
      20_llista_privada
      30_llista_de_difusio
      40_contactans
      50_llista_de_difusio_privada
      60_difusio_membres_upc



- NOTA important:
A partir del 31-01-2019 caldrà passar l'username i password via POST en fer crides a l'API.

Exemples d'ús des de línia de comandes executant una comanda "wget" usant POST per passar l'username/password:

- Executar comanda "lists"

wget --post-data="username=nom.cognom@upc.edu&password=XXXXX" "https://mylist.upc.edu/api/user_api.php?action=lists" -O sortida.txt; cat sortida.txt

=> retornarà el següent codi json (al fitxer sortida.cat): 

[{"homepage":"http:\/\/mylist.upc.edu\/wws\/info\/esistemes","subject":"","listAddress":"esistemes@mylist.upc.edu"},{"homepage":"http:\/\/mylist.upc.edu\/wws\/info\/interlocutorsticsg","subject":"[TICsg]","listAddress":"interlocutorsticsg@mylist.upc.edu"},{"homepage":"http:\/\/mylist.upc.edu\/wws\/info\/istw-upcbarcelona","subject":"Mailing list from ISTW-UPC Barcelona","listAddress":"istw-upcbarcelona@mylist.upc.edu"},{"homepage":"http:\/\/mylist.upc.edu\/wws\/info\/llistamixta","subject":"","listAddress":"llistamixta@mylist.upc.edu"},{"listAddress":"llistaperesborar@mylist.upc.edu","subject":"","homepage":"http:\/\/mylist.upc.edu\/wws\/info\/llistaperesborar"},{"homepage":"http:\/\/mylist.upc.edu\/wws\/info\/smartunivercity-fans","subject":"Llista de supporters de la SMART UniverCITY","listAddress":"smartunivercity-fans@mylist.upc.edu"},{"homepage":"http:\/\/mylist.upc.edu\/wws\/info\/ssi","subject":"[SSI] ","listAddress":"ssi@mylist.upc.edu"}]


 - Executar la comanda "createList" amb template 40_contactans

wget --post-data="username=nom.cognom@upc.edu&password=XXXXX" "https://mylist.upc.edu/api/user_api.php?action=createList&listname=nom-llista-sense-domini&subject=Llista contactans de prova&template=40_contactans&description=Llista contactans per fer proves&topic=Qualsevol.cosa" -O sortida.txt; cat sortida.txt


=> retornarà el següent codi json (al fitxer sortida.cat) si es crea bé:

[True]

 

 

Keywords
treball col·laboratiu llistes correu