EStudy WebService API

Aus THM-Wiki
Wechseln zu: Navigation, Suche

Im Rahmen der Joomla! Programming Weeks 2010 wurde zur Herstellung der Interoperibilität zwischen Joomla und eStudy eine Schnittstelle geschaffen, die es ermöglicht, über einen SOAP-basierten WebService Informationen zwischen beiden Systemen auszutauschen.

Im Folgenden soll nun die eStudy-seitige Implementierung der bereitgestellten Funktionalität beschrieben und aufgezeigt werden, wie diese in anderen Systemen verwendet werden können.

Grundlegendes

Bei der eStudy WebService API handelt sich um eine Schnittstelle, um Informationen zwischen eStudy und einem weiteren System (z.B. Joomla!), über einen SOAP-basierten WebService auszutauschen.

Die Implementierung aller angebotenen Dienste befindet sich im Verzeichnis ROOTFOLDER/web/wsapi und erfolgt mit Hilfe der Zend_Soap-Klassen des Zend-Frameworks.

Für jedes Modul ist ein separater Einstiegspunkt vorgesehen. So wird die Schnittstelle zum Kalender-Modul in dem Script /web/wsapi/calendar.php bereitgestellt. Hier ist vorgesehen, dass die Beschreibung des WebServices bei Aufruf dieses Scripts mit zusätzlichen GET-Parameter wsdl generiert wird.

Implementierung

Wie bereits im Abschnitt Grundlegendes angesprochen, ist vorgesehen für verschiedene Module jeweils eine separate Schnittstelle bereit zu stellen.

Die Klasse WebServiceAPI

Die Klasse WebServiceAPI stellt grundlegende Methoden bereit, die allen WebService-Implementierungen gemein sind. Von besonderer Bedeutung sind hier die beiden Methoden

  • userID($username)
  • authenticate($username,$token)

Sie dienen der Authentifizierung eines Benutzers, sowie der Bereitstellung der eStudy-UserID. Alle weiteren Klassen der WebServiceAPI sind von dieser Klasse abgeleitet.

Implementierung der Funktionalität

Die Funktionalität eines WebServices wird in einer Klasse implementiert. Als Beispiel soll hier ein Ausschnitt aus der Klasse CalendarAPI dienen:

class CalendarAPI extends WebserviceAPI {
    /** This method exports the calendar if the user with given username
     * @return string
     */
    public function iCalendar() {
        ...
        if (! $this->isAuthenticated ) return "NOT AUTHENTICATED"
        ...
        return ...
    }
}

Hat sich ein Benutzer korrekt über den WebService authentifiziert (diese Funktionalität ist in der Basisklasse WebserviceAPI zu finden), wird ihm ein String übergeben, welcher die Kalenderinformationen im iCal-Format repräsentieren.

Bereitstellung einer automatisch generierten WSDL

Zunächst soll hier beschrieben werden, wie mit Hilfe der Klasse Zend_Soap_AutoDiscover eine Beschreibung des angebotenen WebServices veröffentlicht werden kann.

$autodiscover = new Zend_Soap_AutoDiscover();
$autodiscover->setClass('CalendarAPI');
$autodiscover->handle();

Im obigen Beispiel wird eine WSDL-Beschreibung der Funktionalität, welche in der Klasse CalendarAPI implementiert ist, bereitgestellt.

Die so generierte WSDL hat nun folgenden schematischen Aufbau: Calendar wsdl.jpg

Definition der Struktur der Information

Eine weitere Möglichkeit die Informationen zu übertragen, ist die Erstellung einer Entity-Klasse, welche die Elemente der zu übergebenden Information beinhaltet:

class Entities_Event {
    /** ID of event
     * @var int
     */
    public $id;

    /** Type of event
     * @var string
     */
    public $type;

    public function __construct( $data ) {
        $this->mailto = $data['mailto'];
        $this->summary = $data['summary'];
        ... 
    }
}

Wird nun das Script /web/wsapi/calendar.php wie folgt erweitert:

 ...
 $autodiscover->setComplexTypeStrategy('Zend_Soap_Wsdl_Strategy_ArrayOfTypeSequence');
 ...

wird in der generierten WSDL der Datentyp Entities_Event deklariert. Hierdurch ist es möglich, die zu übertragenen Daten strukturiert zu übertragen und diese Struktur auch in der WSDL bekannt zu machen.

Eine Methode der Klasse CalendarAPI kann nun wie folgt aussehen:

...
/** This method exports the calendar as array of event 
 *  entities as defined in WSDL
 * @return Event[]
 */
public function calendar() {
    $result = array();
    ...
    $result[] = new Event(...);
    ...
    return $result;
}

Bei Aufruf dieser WebService-Methode wird der Rückgabewert an Hand der Information in der Entity-Klasse als XML serialisiert übertragen.

In die WSDL wird nun der Aufbau eines Events eingebettet. Hierzu folgender schematischer Aufbau:

Calendar schema.jpg

Behandlung von WebService-Anfragen

Zur Behandlung einkommender WebService-Anfrage genügen nun wenige Zeilen Programmcode:

if (isset($_GET['wsdl'])) {
    $autodiscover->handle();
}
else {
    try {
        $server = new Zend_Soap_Server($autodiscover->getUri()."?wsdl");
        $server->setClass('CalendarAPI');
        $server->handle();
    }
    catch (Exception $e) {
        ...
    }
}

Verwendung des WebServices

Der WebService kann am einfachsten über die Klasse Zend_Soap_Client konsumiert werden:

$client = new Zend_Soap_Client("http://.../wsapi/calendar.php?wsdl");
$client->addSoapInputHeader(
    new SoapHeader(
        "http://schemas.xmlsoap.org/ws/2002/07/utility",
        "authHeader",
        array(
            '<username>',
            '<token>
        )
    ),
    true
);
...

Folgender Aufruf liefert die Kalenderdaten als String im iCal-Format zurück:

...
$ical = $client->icalendar();
...

Durch den Aufruf nachstehenden Aufruf wird ein PHP-Array zurückgeliefert, welches aus mehreren Elementen vom Typ Event besteht:

...
$eventArray = $client->calendar()->item;
...

Dieses kann nun wie jedes Array behandelt werden. Nachfolgend als Beispiel die Ausgabe aller Zusammenfassungen der abgerufenen Kalendereinträge:

...
foreach ($eventArray as $event) {
    echo $event->summary;
}
...