sympa-community.github.io

Incubating the new Sympa documentation site

SOAP/HTTP API

Introduction

SOAP is a protocol (generally over HTTP) that can be used to provide web services. Sympa SOAP server allows to access a Sympa service from within another program, written in any programming language and on any computer. SOAP encapsulates procedure calls, input parameters and resulting data in an XML data structure. The Sympa SOAP server’s API is published in a WSDL document, retrieved through Sympa’s web interface.

The SOAP server provides a limited set of high level functions: See “Supported functions”. Other functions might be implemented in the future. One of the important implementation constraints is to provide services for proxy applications with a correct authorization evaluation process where authentication may differ from classic web methods. The following four cases can be used to access the service:

In any case, scenario authorization is used with the same rules as a mail interface or a normal web interface.

The server is running as FastCGI server, receiving the client SOAP requests via a HTTP server (Apache HTTP Server for example).

Supported functions

Note that all functions accessible through the SOAP interface apply the appropriate access control rules, given the user’s privileges.

The following functions are currently available through the Sympa SOAP server :

Note that when a list parameter is required for a function, you can either provide the list name or the list address. However the domain part of the address will be ignored.

Check the WSDL service description for detailed API information.

Setup

Requirements

HTTP server setup

See appropriate section in “Configure HTTP server”.

Sympa configuration parameters

Other configuration files

Trust remote applications

The SOAP service authenticateRemoteAppAndRun is used in order to allow some remote applications such as a web portal to request the Sympa service as a proxy for the end user. In such cases, Sympa will not authenticate the end user itself, but instead it will trust a particular application to act as a proxy.

This configuration file trusted_applications.conf can be created in $SYSCONFDIR/domain directory or in $SYSCONFDIR directory depending on the scope you want for it. This file is made of paragraphs separated by empty lines and stating with keyword trusted_application. A sample trusted_applications.conf file is provided with Sympa sources. Each paragraph defines a remote trusted application with keyword/value pairs:

You can test your SOAP service using the sympa_soap_client.pl sample script as follows:

$ sympa_soap_client.pl --soap_url=http://web.example.org/sympasoap \
 --service=createList --trusted_application=myTestApp \
 --trusted_application_password='myTestAppPwd' \
 --proxy_vars='USER_EMAIL=userProxy@my.dom.ain' \
 --service_parameters='listA,listSubject,discussion_list,description,myTopic'

$ sympa_soap_client.pl --soap_url=http://web.example.org/sympasoap \
 --service=add --trusted_application=myTestApp \
 --trusted_application_password='myTestAppPwd' \
 --proxy_vars='USER_EMAIL=userProxy@my.dom.ain' \
 --service_parameters='listA,someone@some;domain,name'

Below is a sample Perl code that does a SOAP procedure call (for a SUBSCRIBE sympa command) using the trusted_application feature :

use SOAP::Lite;

my $soap = SOAP::Lite->new();
$soap->uri('urn:sympasoap');
$soap->proxy('http://web.exemple.org/sympasoap');

my $response = $soap->authenticateRemoteAppAndRun('myTestApp',
    'myTestAppPwd', 'USER_EMAIL=userProxy@my.server',
    'subscribe', ['myList@mail.example.org']);

S. Santoro wrote its own PHP Trusted Application library for Sympa.

Client-side programming

Sympa is distributed with two sample clients written in Perl and in PHP. The Sympa SOAP server has also been successfully tested with a UPortal Channel as a Java client (using Axis). The sample PHP SOAP client sampleClient.php is found in sample directory of source distribution.

Depending on your programming language and the SOAP library you are using, you will either directly contact the SOAP service (as with the Perl SOAP::Lite module), or first load the WSDL description of the service (as with PHP nusoap or Java Axis). Axis is able to create a stub from the WSDL document.

The WSDL document describing the service should be fetched through WWSympa’s dedicated URL, e.g. http://web.example.org/sympa/wsdl.

Note: the login() function maintains a login session using HTTP cookies. If you are not able to maintain this session by analyzing and sending appropriate cookies under SOAP, then you should use the authenticateAndRun() function that does not require cookies to authenticate.

Writing a Java client with Axis


Note:


First, download Apache Axis.

You must add the libraries provided with Apache Axis to your CLASSPATH. These libraries are:

Next, you have to generate client Java class files from the sympa WSDL URL. Use the following command:

$ java org.apache.axis.wsdl.WSDL2Java -av <WSDL URL>

For example:

$ java org.apache.axis.wsdl.WSDL2Java -av http://web.example.org/sympa/wsdl

Exemple of screen output during generation of Java files:

  Parsing XML file:  http://web.example.org/sympa/wsdl
  Generating org/example/web/sympa/msdl/ListType.java
  Generating org/example/web/sympa/msdl/SympaPort.java
  Generating org/example/web/sympa/msdl/SOAPStub.java
  Generating org/example/web/sympa/msdl/SympaSOAP.java
  Generating org/example/web/sympa/msdl/SympaSOAPLocator.java

If you need more information or more generated classes (to have the server-side classes or junit testcase classes for example), you can get a list of switches:

$ java org.apache.axis.wsdl.WSDL2Java -h

See the documentation for more details.

Take care of Test classes generated by axis, there are not useable as are. You have to stay connected between each test. To use junit testcases, before each SOAP operation tested, you must call the authenticated connexion to Sympa instance.

Here is a simple Java code that invokes the generated stub to perform a casLogin() and a which() on the remote Sympa SOAP server:

  SympaSOAP loc = new SympaSOAPLocator();
  ((SympaSOAPLocator)loc).setMaintainSession(true);
  SympaPort tmp = loc.getSympaPort();
  String _value = tmp.casLogin(_ticket);
  String _cookie = tmp.checkCookie();
  String[] _abonnements = tmp.which();

The test command line SOAP client

Sympa distribution includes a simple command line application that allows you to test SOAP request towards your Sympa SOAP server. This script is named sympa_soap_client.pl and is located in $SCRIPTDIR directory.

The four methods available through the Sympa SOAP server can be tested using this tool. There is no explicit option to tell what access method is used. It is inferred based on what options are provided to the script.

Getting the email associated to a session id

You must use the id of a session actually used at the time you launch the command. It is the value of the “sympa_session” cookie set when accessing to the HTTP interface.

Command line

$ sympa_soap_client.pl \
 --soap_url=<SOAP server URL> \
 --cookie=<cookie identifier>

Expected output

error : get_email_cookie
cookie : 65354224256806


getEmailUserByCookie....
0
        'mail@renater.fr'

Using the Sympa SOAP functions with the command line tool

It is done by calling the script and providing two kind of arguments :

Actually, providing the HTTP cookie to a command line sums up in providing a session id, i.e. a simple number. You must use the value of a session cookie actually used at the time you launch the command. It is the “sympa_session” cookie set when accessing to the Sympa web interface.

$ sympa_soap_client.pl --soap_url=<SOAP server URL> \
 --service=<a sympa service> \
 --service_parameters=<value1,value2,value3> \
 --session_id=<cookie identifier>

The options used are:

Authentication using a user name and password

$ sympa_soap_client.pl --soap_url=<SOAP server URL> \
 --service=<a sympa service> \
 --service_parameters=<value1,value2,value3> \
 --user_email=<email> \
 --user_password=<password>

The options used are:

Access through a trusted application

$ sympa_soap_client.pl --soap_url=<SOAP server URL> \
 --service=<a sympa service> \
 --service_parameters=<value1,value2,value3> \
 --cookie=<cookie identifier> \
 --trusted_application=<app name> \
 --trusted_application_password=<password> \
 --proxy_vars=<id=value,id2=value2>

The options used are:

Sympa SOAP services and the command line tool

This is a description of how to use the Sympa SOAP services using the command line tool. The parameters are given in the same order they must be found in the command tool option service_parameters. They must be provided as a comma separated list, without spaces. Don’t forget to escape characters that would break the command line, such as spaces, exclamation marks and so on.


Note:


login

No object here: this is the service used to log when the command tool uses a username and password.

casLogin

No object here.

authenticateAndRun

No object here: this the service used by the command line tool to call the other services, when authentication is done through session id or user name + password.

authenticateRemoteAppAndRun

No object here: this the service used by the command line tool to call the other services, when testing trusted applications.

lists

The parameters are optional.

Parameters:

Output example:

lists....
0
        'homepage=http://domain.tld/sympa/info/amietestdv01;subject=Amical;listAddress=amietestdv01@domain.tld'
1
        'homepage=http://domain.tld/sympa/info/archeologie;subject=Liste sur l'archéologie;listAddress=archeologie@domain.tld'
2
        'homepage=http://domain.tld/sympa/info/blackmambo;subject=A black mambo;listAddress=blackmambo@domain.tld'
3
        'homepage=http://domain.tld/sympa/info/bluemambo;subject=Another mambo. This one is blue.;listAddress=bluemambo@domain.tld'

complexLists

The parameters are optional.

Parameters:

Output example:

AuthenticateAndRun complexLists....
0
        _homepage_
                'http://domain.tld/sympa-dv/info/amietestdv01'
        _listAddress_
                'amietestdv01@domain.tld'
        _subject_
                'Amical'
1
        _homepage_
                'http://domain.tld/sympa-dv/info/archeologie'
        _listAddress_
                'archeologie@domain.tld'
        _subject_
                'List sur l'archéologie'
2
        _homepage_
                'http://domain.tld/sympa-dv/info/blackmambo'
        _listAddress_
                'blackmambo@domain.tld'
        _subject_
                'A black mambo'
3
        _homepage_
                'http://domain.tld/sympa-dv/info/bluemambo'
        _listAddress_
                'bluemambo@domain.tld'
        _subject_
                'Another mambo. This one is blue.'

info

Parameters:

Output example:


which

All arguments are mandatory (at least with an empty value).

Parameters:

Output example:

which....
0
        'isOwner=1;homepage=http://domain.tld/sympa/info/amietestdv01;subject=Amical;listAddress=amietestdv01@domain.tld;isEditor=0;isSubscriber=0'
1
        'isOwner=1;homepage=http://domain.tld/sympa/info/archeologie;subject=Liste sur l'archéologie;listAddress=archeologie@domain.tld;isEditor=0;isSubscriber=0'
2
        'isOwner=1;homepage=http://domain.tld/sympa/info/blackmambo;subject=A black mambo;listAddress=blackmambo@domain.tld;isEditor=0;isSubscriber=0'
3
        'isOwner=1;homepage=http://domain.tld/sympa/info/bluemambo;subject=Another mambo. This one is blue.;listAddress=bluemambo@domain.tld;isEditor=0;isSubscriber=0'

complexWhich

All arguments are mandatory (at least with an empty value).

Parameters:

Output example:

complexWhich....
0
        _homepage_
                'http://dev-sympa.renater.fr/sympa-dv/info/redmambo'
        _isEditor_
                '0'
        _isOwner_
                '1'
        _isSubscriber_
                '0'
        _listAddress_
                'redmambo@dev-sympa.renater.fr'
        _subject_
                'Amical'
1
        _homepage_
                'http://dev-sympa.renater.fr/sympa-dv/info/bluemambo'
        _isEditor_
                '1'
        _isOwner_
                '1'
        _isSubscriber_
                '0'
        _listAddress_
                'bluemambo@dev-sympa.renater.fr'
        _subject_
                'Another mambo. This one is blue.'
2
        _homepage_
                'http://dev-sympa.renater.fr/sympa-dv/info/archeologie'
        _isEditor_
                '1'
        _isOwner_
                '1'
        _isSubscriber_
                '0'
        _listAddress_
                'archeologie@dev-sympa.renater.fr'
        _subject_
                'Liste sur l'archéologie'
3
        _homepage_
                'http://dev-sympa.renater.fr/sympa-dv/info/blackmambo'
        _isEditor_
                '0'
        _isOwner_
                '1'
        _isSubscriber_
                '0'
        _listAddress_
                'blackmambo@dev-sympa.renater.fr'
        _subject_
                'A black mambo'

amI

Parameters:

Output example:

param: blackmambo
param: owner
param: david.verdin@renater.fr
Using Session_id 48339436597794


AuthenticateAndRun amI....
0
        '1'

review

Parameters:

Output example:

review....
0
        'mail1@renater.fr'
1
        'mail2@renater.fr'
2
        'mail3@renater.fr'

subscribe

Parameters:

Output example:

subscribe....
0
        '1'

signoff

Parameters:

Output example:

signoff....
0
        '1'

add

Parameters:

Output example:

add....
0
        ''

del

Parameters:

Output example:

del....
0
        '1'

createList

Parameters:

Output example:

param: orangemambo
param: Dude !
param: hotline
param: La liste verte
param: computing
Using Session_id 4860001445687


AuthenticateAndRun createList....
0
        '1'

closeList

Parameters:

Output example:

param: orangemambo
Using Session_id 4860001445687


AuthenticateAndRun closeList....
0
        '1'

CC BY-SA 4.0 Unless otherwise specified, the contents of this document are licensed under the Creative Commons - Attribution - ShareAlike license. For more details see LICENSE and AUTHORS.

Theme originally designed by orderedlist