© saicle/Shutterstock.com
Eine Einführung in Apigility

Nur noch kurz die Welt retten … ein API bauen


Auf der ZendCon 2013 wurde erstmals das auf dem Zend Framework 2 basierende Projekt Apigility vorgestellt. Damit können auf einfache Weise APIs erstellt und betrieben werden, um z. B. in mobilen Anwendungen direkt vom Frontend angesprochen zu werden. Anfang Mai 2014 ist nun das ­erste stabile Release erschienen. Es ist also an der Zeit, sich intensiver mit Apigility auseinanderzusetzen.

Damit Sie die Beispiele selbst nachvollziehen können, steht eine Beispielanwendung auf GitHub für Sie bereit [1]. Sie können das Projekt wie folgt klonen (bitte ggf. die Verzeichnisse anpassen) und installieren:

cd /home/devhost git clone https://github.com/RalfEggert/phpmagazin.apigility cd phpmagazin.apigility git checkout step1 php composer.phar selfupdate php composer.phar install

Um die Installation abzuschließen, müssen Sie noch die Schreibrechte für einige Verzeichnisse anpassen, damit Apigility Änderungen vornehmen kann:

> sudo chmod 777 -R config/ > sudo chmod 777 -R data/ > sudo chmod 777 -R module/ 

Zum Schluss muss Apigility mit php public/index.php development enable in den Entwicklungsmodus gebracht werden. Danach richten Sie noch einen Virtual Host für die Adresse phpmagazin.apigility ein. Wenn Sie nun http://phpmagazin.apigility/ in Ihrem Browser aufrufen, sollte die Seite ungefähr wie in Abbildung 1 dargestellt aussehen. Zu guter Letzt müssen Sie noch eine MySQL-Datenbank anlegen und dort einen Dump aus der Datei /data/sql/mysql.dump.sql einspielen. Alternativ können Sie auch jede andere Datenbank verwenden, die vom Zend Framework 2 und damit von Apigility unterstützt wird [2].

eggert_apigility_1.tif_fmt1.jpgAbb. 1: Willkommen auf phpmagazin.apigility

Als Beispiel wollen wir ein kleines API für ein Tippspiel zur Fußballweltmeisterschaft 2014 umsetzen. Wenn Sie den Datenbank-Dump eingespielt haben, können Sie die Struktur der Anwendung genauer betrachten. Es gibt insgesamt drei Tabellen, wie Sie Abbildung 2 entnehmen können. Alle Listings zu diesem Artikel, die nicht im Magazin abgedruckt sind, finden Sie sowohl auf GitHub [3] als auch im Repository im Verzeichnis /listings/. Nun können wir loslegen.

eggert_apigility_2.tif_fmt1.jpgAbb. 2: Die Tabellen für unser Projekt

Was ist Apigility überhaupt?

Mit Apigility [4] können Sie qualitativ hochwertige APIs erstellen und betreiben. Beim Einsatz eines API für die Datenhaltung können Sie diese sehr einfach von der Präsentationslogik trennen. Somit können Sie mobile Websites und Applikationen im Frontend entwickeln und die Daten mithilfe von Apigility per REST- oder RPC-Web-Service anbinden. Die Rückgabe der angeforderten Daten erfolgt im JSON-Format, das clientseitig von JavaScript verarbeitet werden kann. Apigility setzt auf dem Zend Framework 2 auf und bietet einige sehr interessante Features:

  • RESTful Web Services

  • RPC Web Services

  • Datenformat JSON bzw. JSON HAL

  • Versionierung

  • Codebasierte und datenbankbasierte Services

  • Problemdetails für HTTP-API

  • Datennormalisierung und -validierung

  • Authentifizierung per HTTP Basic/Digest und OAuth 2.0

  • Dokumentation per HTML und Swagger

Für diesen Beitrag wurde Apigility 1.0.3. verwendet. Die Pläne für die kommende Version 1.1 lassen sich ebenfalls sehen, dazu zählen Anbindungen an Doctrine und MongoDB, HTTP Caching und das automatische Erkennen der Datenbank. Vielleicht ist das neue Release bereits erschienen, wenn Sie diesen Artikel lesen.

Zur weiteren Einführung sollten Sie sich bei Gelegenheit auch die Videos zu Apigility anschauen [5]. Darin wird unter anderem der Einstieg in die Software erläutert sowie gezeigt, wie Sie eine Dokumentation für Ihr API bereitstellen können. Zudem bietet die Website eine ausführliche Dokumentation von Apigility sowie Hinweise zum Download und zur Installation.

Unser erstes API

Um beginnen zu können, klicken Sie auf der Startseite von http://phpmagazin.apigility/ auf den Button „Get Started!“ Der folgende Bildschirm zeigt uns eine Übersicht über alle bereits eingerichteten APIs und deren Einstellungen. Wir beginnen mit den Einstellungen für den Datenbankadapter und wählen deshalb aus dem Seitenmenü den Punkt „Database Adapters“ und danach den Button „Create New DB Adapter aus. Vergeben Sie einen Namen für Ihren Adapter, wählen einen Treibertyp aus und geben Datenbanknamen sowie alle Zugangsdaten ein. Nach dem Klicken auf den Button „Create DB Adapter“ wird Ihr Datenbankadapter angelegt. Wenn Sie den Adapter nach dem Speichern nochmals anklicken, sollte es in etwa wie in Abbildung 3 aussehen.

eggert_apigility_3.tif_fmt1.jpgAbb. 3: Unser erster Adapter

Wir möchten zuerst mit der Tabelle „teams“ beginnen, die alle teilnehmenden Mannschaften an der WM enthält, und dafür ein API erstellen, das nur lesende Zugriffe erlaubt. Dafür rufen Sie aus dem Hauptmenü den Punkt „APIs“ auf und klicken auf den Button „Create New API“. Als Namen verwenden wir „WM2014API“. Sollte Ihnen nach dem Speichern kein API in der Liste angezeigt werden, laden Sie die Seite in Ihrem Browser bitte einmal neu, um das neue API auszuwählen. Sie haben an dieser Stelle die Möglichkeit, einen REST oder einen RPC-Service zu erstellen und die Autorisierung sowie die Versionierung zu konfigurieren. Klicken Sie bitte auf den Punkt „REST Services“ im Seitenmenü und danach auf den Button „Create New REST Service“. Da wir eine Datenbank anbinden möchten, klicken Sie bitte den Reiter „DB-Connected“ an und wählen den bereits erstellten Datenbankadapter aus. Bei dem Tabellennamen geben Sie „teams“ ein und klicken auf den Button „Create DB-Connected REST Service“.

Jetzt können wir unser API schon das erste Mal testen. Für den Test eines RESTful Web Service gibt es viele Möglichkeiten. Als sehr beliebtes Mittel zum Zweck hat sich der Postman Rest Client [6] gemausert, der im Chrome-Browser als App installiert und genutzt werden kann. Alternativ können Sie auch den RESTClient [7] oder cURL auf der Kommandozeile verwenden. Wenn Sie Postman gestartet haben, geben Sie bei Request-URL http://phpmagazin.apigility/teams ein und wählen GET als HTTP-Request-Modus aus. Klicken Sie jetzt auf den „Send“-Button, und Sie sollten eine JSON-Struktur zurückerhalten, die in etwa wie in Abbildung 4 aussehen sollte.

Bei dieser besonderen JSON-Struktur handelt es sich um HAL JSON. HAL steht für „Hypermedia Application Language“ und ist eine offene Spezifikation zur Beschreibung einer generischen Struktur für RESTful-Ressourcen [8]. Apigility sendet die Daten dafür mit dem generischen Media-Type application/hal+json zurück. In dieser Struktur ist eine Eigenschaft _links enthalten, die in unserem Beispiel die Request-URLs für die aktuelle, die erste, die letzte und die nächste Seite enthält. Die eigentlichen Daten finden sich in der Eigenschaft _embedded, wobei die einzelnen Entitäten wieder über eine Eigenschaft _links verfügen. Ganz am Ende der Struktur wird noch die Anzahl der Seiten, die Anzahl der Entitäten pro Seite sowie die Anzahl aller Entitäten zurückgegeben. Mit diesen Angaben ist es sehr einfach, eine Paginierung der Daten umzusetzen. Weitere Informationen zu HAL finden Sie auch in der Apigility-Dokumentation [9].

eggert_apigility_4.tif_fmt1.jpgAbb. 4: Das Ergebnis der ersten Anfrage an unser API

Wenn Sie den Request-URL im Postman auf http://phpmagazin.apigility/teams/ger ändern und die Anfrage absenden, erhalten Sie übrigens direkt die Daten einer Entität. Bei einzelnen Entitäten finden sich die Eigenschaften nicht unter _embedded sondern di...

Neugierig geworden? Wir haben diese Angebote für dich:

Angebote für Gewinner-Teams

Wir bieten Lizenz-Lösungen für Teams jeder Größe: Finden Sie heraus, welche Lösung am besten zu Ihnen passt.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang