Schlagwort-Archive: soap

Stud.IP-Webservices Teil 2

Im letzten Artikel wurde die Infrastruktur hinter den Stud.IP-Webservices vorgestellt und auf den PHPXML-RPC-Debugger hingewiesen. Heute werden wir einen einfachen  echo-Webservice schreiben, der einen zugesendeten Text einfach wieder zurück schickt. Natürlich braucht man dafür eine eigene Stud.IP-Installation zum ausprobieren. Wie man Stud.IP installiert, steht in der Installationsanleitung. Wichtig für funktionierende Webservices: Es müssen zwei Konfigurationsvariablen in der Datei config/config_local.inc.php angepasst werden:

  • $WEBSERVICES_ENABLE legt fest, ob die Stud.IP-Webservices überhaupt aktiv sind. Notwendigerweise muss dieser auf TRUE gestellt werden, damit man mit den Stud.IP-Webservices experimentieren kann.
  • $STUDIP_API_KEY stellt eine Art Passwort dar, mit dem in manchen Webservices geprüft wird, dass der Request authorisiert ist. Füllen Sie diese Konfigurationseinstellung mit einem langen String. Lassen Sie sich zum Beispiel einen generieren.

Ihr Stud.IP-System sollte jetzt Webservice-Requests bearbeiten. Überprüfen Sie die Endpoints:

Für den SOAP- und XML-RPC-Endpoint sollten Sie die Dokumentation der zur Verfügung stehenden Methoden vorfinden.

Dokumentation der XML-RPC-API von Stud.IP

Dokumentation der XML-RPC-API von Stud.IP

Nachdem nun alle Puzzleteile an ihrem Platz sind, kann es mit der echo-Methode losgehen. Den entsprechenden Quellcode habe ich in einem entsprechenden Stud.IP-Branch bei github.com (commit 8cd17b) abgelegt.

Eine Funktion, die ihr Argument einfach zurückgibt, sieht in PHP so aus:

function echo($string) {
  return $string;
}

Eigentlich sind wir damit schon fast fertig, damit daraus aber ein Webservice wird, müssen noch ein paar Formalitäten abgewickelt werden.

Zunächst möchte man diese Funktion sicher nicht im globalen Namensraum liegen haben. Da allerdings erst mit PHP 5.3 tatsächliche Namensräume vorhanden sind, behelfen wir uns mit einer Klasse, in der wir die Funktion als Methode einbetten:

class ExampleService {
  function echo($string) {
    return $string;
  }
}

Diese Klasse legen wir in einer neuen Datei lib/webservices/services/example_webservice.php ab.

Außerdem fallen weitere Konventionen an, denen genüge getan werden muss. Zum einen müssen die Endpoints von unserem Webservice erfahren. Dazu öffnet man die Dateien

  • public/jsonrpc.php
  • public/soap.php
  • public/xmlrpc.php

und fügt dort jeweils in ca. Zeile 38 ein:

require_once 'lib/webservices/services/example_webservice.php';

Außerdem muss der Name unserer neuen Klasse in die Argumentliste bei der Instanzierung der Server-Objekte aufgenommen werden. Für beispielsweise die Datei soap.php fügen wir deshalb den String „ExampleService“ so in Zeile 45 an:

$delegate =& new Studip_Ws_SoapDispatcher('UserService', 'SessionService', 
  'SeminarService', 'ContentmoduleService', 'LectureTreeService', 
  'InstituteService', 'ExampleService');

Für XML-RPC und JSON-RPC tut man das genauso.

Als nächstes Zugeständnis müssen Funktionen, die über einen Webservice zugänglich gemacht werden sollen, umbenannt und angemeldet werden. Die Umbenennung ist nicht schwer: Solche Funktionen müssen einfach auf „_action“ enden. (Würde man das nicht tun, dürfte man z.B. niemals eine Funktion „list“ haben, da dies in PHP ein reserviertes Wort ist.)

Die Anmeldung einer Funktion geschieht im Konstruktor der Klasse. Dort muss der Name (ohne das „_action“) und die Signatur genannt werden. Über die Signatur sprechen wir in einem zukünftigen Artikel, so dass hier nur der fertige Code gezeigt wird:

class ExampleService extends Studip_Ws_Service {

  function __construct() {
    $this->add_api_method('echo',
                          array('string'),
                          'string',
                          'example echo service');
  }

  function echo_action($string) {
    return $string;
  }
}

Die Argumente der Anmeldung (#add_api_method) im Konstruktor lassen sich so entschlüsseln:

  • Der Name der Funktion lautet „echo“ (ohne „_action“!).
  • Der nächste Parameter enthält die Typen der Funktionsargumente als Liste. Wir verlangen einen Parameter, der ein String sein soll, so dass die Typliste so aussieht: „array(’string‘)“.
  • Der dritte Parameter gibt den Typ des Rückgabewertes an. Hier ist das wie beabsichtigt ein String.
  • Der letzte Parameter enthält eine kurze textuelle Beschreibung der Funktion.

Und damit sind wir schon fertig. Rufen Sie einen Endpunkt auf (z.B. für XML-RPC). Dort taucht nun in der Liste unsere echo-Methode auf. Probieren Sie sie z.B. im Debugger aus. Wie zu erwarten war, funktioniert alles einwandfrei 🙂

PHP-Funktionen über die studip-ws-Bibliothek ist also ganz einfach. Wenn man von den beschriebenen, minimalen Anforderungen absieht, ist dies nicht schwieriger, als eine Funktion in PHP zu schreiben, ohne jemals XML oder SOAP gesehen zu haben.

Im nächsten Teil geht es dann um die Signaturen der Funktionen. Bis dahin viel Spaß mit ihrem neuen echo-Service.

Stud.IP-Webservices Teil 1

Im Stud.IP-Entwicklerforum wurde nachgefragt, wie man eine weitere Methode zur Verfügung stellen könne. In den kommenden Tagen werde ich versuchen, die wichtigsten Sachen zu diesem Themengebiet vorzustellen.

Grundsätzlich wird für die (RPC-basierten) Webservices in Stud.IP die Bibliothek studip-ws verwendet, die sich in einer üblichen Stud.IP-Installation im Verzeichnis /vendor/studip_ws/ befindet. Grundsätzlich ist diese Bibliothek die Abstraktion zweier anderer:

Die Motivation für eine weitere Abstraktion über diesen schon nicht unbedingt simplen Protokollen bestand darin, bei der Implementation von Webservices möglichst wenig mit den teilweise ungewöhnlichen Details dieser Protokolle zu tun zu haben. Stattdessen war die Idealvorstellung, Methoden in Klassen in »normalem« PHP zu implementieren. Solange man sich in einer gewissen Untermenge von PHP bewegt, funktioniert das alles sehr gut.

Leider ist es für die Verwendung von SOAP unerlässlich, Signaturen für die zur Verfügung gestellten Methoden zu definieren. Aus dieser Einschränkung resultieren ein paar Eigenheiten, die unter anderem in den kommenden Artikeln vorgestellt werden sollen.

Um ein bisschen praktischen Nutzwert in diesem Artikel zu geben, soll der in der PHPXML-RPC-Bibliothek enthaltene Debugger vorgestellt werden. Wer den Debugger nicht selbst installieren möchte, kann mit genügend Vertrauen die öffentliche Demo-Version ausprobiert werden.

Trägt man dort in das Textfeld »Address« den Wert »phpxmlrpc.sourceforge.net« und in das Textfeld »Path« den Wert »/server.php«, werden einem nach Klick auf den Knopf »Execute« alle Methoden des eingetragenen XML-RPC-Servers aufgelistet. Von dort ausgehend können die Signaturen der Methoden untersucht werden oder auch tatsächliche RPCs ausgeführt werden.

Viel Spaß damit und bis zum nächsten Artikel, bei dem in einem (aktuellen) Stud.IP  eine weitere Methode hinzugefügt wird.