Heute hatte ich nach langer Zeit einmal wieder eine interessante Unterhaltung über Schnittstellen. Überhaupt befasse ich mich in letzter Zeit irgendwie häufiger mit Schnittstellentechniken - insbesondere mit SOAP, RPC im Allgemeinen und natürlich RESTful APIs. So irgendwie habe ich auch das Gefühl, dass die API - also das Application Programming Interface - irgendwie massentauglich geworden ist.

Ich möchte aber mal ein bisschen weiter ausholen und in die Vergangenheit schauen, bevor ich mich der eiskalten Praxis zuwende. Es muss so etwa das Jahr 2004 gewesen sein, da ich einen Vortrag über das SOAP Protokoll hielt, welches auf HTTP aufsetzt. Dies tat ich also etwa ein Jahr nachdem Version 1.2 verabschiedet wurde. Schon damals war man sich nicht richtig sicher, inwieweit SOAP sich durchsetzen würde. Heute sieht das bedeutend anders aus. Auf den Nutzen möchte ich aber später nocheinmal eingehen.

Einen SOAP Service mit PHP entwickeln

Es war lange relativ schwierig gute Bibliotheken für die Verwendung von SOAP in PHP zu finden. Schließlich möchte man ja nicht gezwungen sein eine eigene Bibliothek zu schreiben, denn dann werden einige Vorteile von SOAP überflüssig und es macht wirklich keinen sonderlichen Spaß eine eigene SOAP Bibliothek entwickeln zu müssen. Ich habe bereits ein paar Mal eigene SOAP Bibliotheken - sowohl in PHP als auch anderen Sprachen - entwickelt, weil sich die Entwickler des Service nicht an den Standard hielten - ich denke evtl, weil sie ihn nicht verstanden haben.

Für PHP und SOAP empfehle ich die Bibliothek NuSOAP (erhätlich bei SourceForge). NuSOAP ist Open Source, untersützt SOAP 1.1 komplett und benötigt keine PHP Extensions. Für meinen Blog, den Du hier gerade liest, habe ich mit NuSOAP einmal einen Service programmiert, mit welchem man alle Artikel auslesen kann.

/* config file for general configs */
require_once("../config.php");

/* use the database for queries */
require_once("../class/database.class.php");

/* nusoap library for SOAP */
require_once("../lib/Nusoap/nusoap.php");

/* article service api server */
$soap = new soap_server;

// configure the WSDL to show up on ?wsdl requests
$soap->configureWSDL('ArticleApiService', "http://".CONFIG_CDN_PRIMARY_DOMAIN."/");

// define soap interop as default standard schema
$soap->wsdl->schemaTargetNamespace = 'http://soapinterop.org/xsd/';

// add the complex type for the article itself
$soap->wsdl->addComplexType(
    'articleList',
    'complexType',
    'array',
    'all',
    '',
    array(
     'articleTitle'=>array('name'=>'articleTitle','type'=>'xsd:string'),
     'articleBody'=>array('name'=>'articleBody','type'=>'xsd:string'),
     'articleLink'=>array('name'=>'articleLink','type'=>'xsd:string'))
);


// register the methods
$soap->register(
    'getArticleList',
    array(), array('List' => 'tns:articleList'),
    'http://soapinterop.org/'
);

$soap->service(isset($HTTP_RAW_POST_DATA) ?
    $HTTP_RAW_POST_DATA : '');


/* getArticleList method implementation */
function getArticleList() {
	$articeList = array(); // result object
	
	$db = new database();
	$dblist = $db->getArticleList();
	for($a=0;$agetArticle($dblist[$a]["url"]);
		$articeList[$a] = array("articleTitle" => $dbarticle["title"], 
							"articleBody" => $dbarticle["body"],
							"articleLink" => "http://".CONFIG_CDN_PRIMARY_DOMAIN
												."/".$dbarticle["url"].".html");
	}

	return $articeList; // return result
}

Die Methoden nach der Instanzierung sind eigentlich selbst erklärend. Die Methode "configureWSDL" definiert, dass beim Anhängen von "?wsdl" als query parameter entsprechend die WSDL Datei ausgegeben wird. Diese befindet sich dann hier: http://www.kammerath.net/api/article.php?wsdl. Als Schema Namespace verwende ich hier den Standard.

Mit der Methode "addComplexType" füge ich einen "komplexen Typen" zur WSDL Datei hinzu. Einen solchen muss ich immer dann definieren, wenn ich in einer Methode nicht nur einen einfachen Datentypen wie einen String oder Integer zurückgeben möchte. Da es sich bei PHP schwache, implizite und dynamische Typisierung verwendet, SOAP jedoch auf expliziter und starker Typisierung aufsetzt, müssen wir die Datentypen unserer Rückgabewerte und Parameter  definieren. In der Methode "register" sehen wir, dass neben dem Namen "getArticleList" als zweiter Parameter ein leeres Array angegeben ist (heißt: kein Parameter) und als Rückgabewert unser komplexer Typ mit dem Instanznamen "List". Ganz unten ist dann entsprechend die Methode in PHP runterprogrammiert.

Das war es dann auch schon und nun kann man den Service in verschiedenen Programmiersprachen auf verschiedenen Betriebssystemen verwenden. Ich persönlich empfehle für das Testen und Entwickeln von SOAP Diensten die Software soapUI. Sie ist auch auf dem Screenshot am Anfang des Artikels. Es ist durchaus auch hilfreich, zu verstehen und zu sehen, wie SOAP auf HTTP funktioniert. Dafür eignet sich soapUI super, man kann aber schlimmstenfalls auch auf Wireshark zurückgreifen. Wireshark empfehle ich insbesondere dann, wenn Entwickler von SOAP Diensten Abweichungen vom Standard eingebaut haben. Ein bekanntes Beispiel ist z.B. "SOAP with Attachments" oder kurz SwA.

Verwenden von SOAP Diensten mit PHP

Das Ausführen von Methoden mit SOAP und PHP ist noch einfacher als das Entwickeln eines Dienstes. Alles was wir dazu mit NuSOAP machen müssen, ist einen SOAP Client instanzieren, als Parameter die Dienst-URL übergeben und fertig. Anschließend können wir auch entsprechend die Methoden ausführen und erhalten die Ergebnisse direkt als PHP Objekte.

// Pull in the NuSOAP code
require_once('nusoap.php');
// Create the client instance
$client = new soapclient('http://www.kammerath.net/api/article.php');
// Call the SOAP method
$result = $client->call('getArticleList', array());
// Display the result
print_r($result);

In diesem Fall erhalten wir dann als $result entsprechend die oben definierte articleList als Array. Zusammengefasst ist der Client also lediglich 2 Zeilen groß. Mit REST XML müssten wir hier noch HTTP Abfragen (mind. mit file_get_contents) durchführen und zu JSON serialisieren oder XML parsen. Näheres zu den Unterschieden im nächsten Abschnitt.

Vorteile von SOAP mit PHP gegenüber REST mit XML oder JSON

Viele Dienstanbieter im Internet verwenden mittlerweile neben SOAP für Ihre APIs auch noch REST mit XML oder JSON. Letzteres ist sehr beliebt geworden, da es z.B. in PHP sehr einfach deserialisiert werden kann. REST API Dienste funktionieren meistens so, dass man GET Parameter überträgt und als Ergebnis JSON oder XML Daten bekommt. JSON kann man dann deserialisieren und XML entsprechend parsen.

JSON lässt sich zwar schnell und einfach serialisieren und deserialisieren, es gibt aber nur eine implizite Typisierung und keine explizite - so wie bei SOAP. Des Weiteren gibt es bei JSON und XML REST APIs auch überhaupt keine Dienstebeschreibung wie die WSDL bei SOAP. Ändert der Entwickler des Dienstes diesen also ohne die Dokumentation ordentlich weiter zu führen, dann kann man die Eingabe und Ausgabe Parameter nur Testen und Erraten. Mit SOAP's WSDL hat man immer automatisiert eine Dienstbeschreibung, die korrekt ist. Denn wäre die WSDL für den Dienst nicht korrekt, würde dieser auch nicht funktionieren. Die gängigen Client Bibliotheken in .NET, PHP oder Java berufen sich immer auf die mit WSDL angegebenen Diensteinformationen.

Häufig kommt auch sog. JSON-RPC zum Einsatz. Dies ist kein Standard und beschreibt lediglich das Verfahren, dass anstelle von HTTP GET Parametern JSON Objekte per POST übertragen werden. Es wird also ähnlich wie SOAP agiert, jedoch mit JSON und ohne Dienstbeschreibung.

Anwendungsgebiete von SOAP mit PHP

Für SOAP gibt es mittlweile eine Fülle von Anwendungsszenarien und so gut wie jede größere Software oder jedes größere System verfügen zusätzlich auch über SOAP Schnittstellen, um die Individualisierung zu erlauben und sich in Unternehmensprozesse eingliedern zu können. Ein Beispiel für meine SOAP Schnittstelle wäre z.B. dass wenn Nutzer sich über neue Artikel per E-Mail informieren wollten, könnte das System welches die E-Mails versendet über die SOAP Schnittstelle die Artikel abfragen und E-Mails versenden, sobald ein neuer Artikel online ist. Ich möchte aber einmal ein paar interessante und bekannte SOAP Dienste vorstellen.

• Google AdWords API zum Steuern von AdWords Werbeanzeigen bei Google
• Authorize.Net von CyberSource bietet mit dem Merchant Web Service Kreditkartenabrechnung
• Bing API v2 bietet eine SOAP Schnittstelle, um das Internet zu durchsuchen
• DeveloperGarden.com von der Deutschen Telekom bietet eine Fülle großartiger APIs an inkl. SMS Versand, Telefonanrufe und vielem mehr.

Wer noch mehr SOAP APIs sehen möchte, dem kann ich die Seite ProgrammableWeb.com sehr empfehlen. Hier findet man tolle Übersichten über alle möglichen APIs. Auch JSON APIs wie z.B. die von Twitter oder Facebook. Wer SOAP also von der Client Seite einfach einmal ausprobieren möchte, der findet hier großartige Möglichkeiten.

Bücher zum Thema „PHP SOAP“