Wer sein TYPO3 Projekt um eine eigene RESTApi Schnittstelle erweitern möchte, muss das nicht zwingen „von Grund auf“ selbst machen. Im TYPO3 Repository (TER) findet man einige Extensions, die als solide und gut erweiterbare Grundlage dienen können.
Da wir vor wenigen Tagen unsere Extension „nnrestapi“ im TER veröffentlicht haben, wollten wir einen kleinen Vergleich der Lösungen hier zeigen – jede der Lösungen hat Vor- und Nachteile und die Entscheidung für die „richtige“ TYPO3 RestApi-Extension ist am Ende auch eine Frage der persönlichen Vorlieben und Anforderungen an das Projekt.
In dieser Gegenüberstellung vergleichen wir einige der gängigen „Herausforderungen“ vor der jeder Entwickler steht, wenn er in der Umsetzung eines JSON-basierten REST Servers ist, der als Basis TYPO3 nutzt.
Häufig sind das:
- Die Extension sollte alle gängigen HTTP-Request-Types unterstützen (auch PUT, PATCH und DELETE)
- Das Routing sollte entweder möglichst standardisiert sein – oder zumindest flexibel konfigurierbar
- Die API sollte problemlos Domain-Models inkl. Relationen in JSON konvertieren können
- Die API sollte aus dem empfangenen JSON Modelle erzeugen (und mergen / „PATCH“) können
- Authentifizierung sollte möglich sein, Endpoints müssen sich vor öffentlichen Zugriff schützen lassen
- Datei-Uploads sollten möglich sein
- Unterstützung von Mehrsprachigkeit wäre optimal
Die TYPO3 Rest Api Extensions im Vergleich
Bei der Auswahl beschränken wir uns nur auf Extensions, die im TER unter dem Suchbegriff „REST“ auffindbar waren (Ausnahme: sg_rest ist nur über github verfügbar) und die eine aktuellere Version von Typo3 (min. Version 9) unterstützen. Wir kamen so zu folgender Liste:
EXT:rest REST
https://extensions.typo3.org/extension/rest
EXT:t3api T3api
https://extensions.typo3.org/extension/t3api
EXT:nnrestapi TYPO3 Rest Api
https://extensions.typo3.org/extension/nnrestapi
EXT:restler restler
https://extensions.typo3.org/extension/restler
EXT:routes Extbase YAML Routes
https://extensions.typo3.org/extension/routes
EXT:slimphp_bridge
https://github.com/b13/slimphp-bridge
EXT:app_routes App Routes
https://extensions.typo3.org/extension/app_routes
EXT:sg_rest SG REST
https://gitlab.sgalinski.de/typo3/sg_rest
Disclaimer
@Alle_Autoren der oben genannten Extensions: Aufgrund teilweise sehr knapper Dokumentationen fiel uns bei dem folgenden Vergleich teilweise schwer, alle Features vollständig zu entdecken und verstehen. Wir bitten um Nachsicht – oder noch besser: Um Korrektur! Sollten wir in dem Vergleich grobe Fehler gemacht haben, schreibt uns bitte einen Kommentar! Ziel dieses Beitrages ist es nicht, für unsere eigene Extension „Werbung“ zu machen, sondern die TYPO3 Restful Api Extensions möglichst objektiv zu vergleichen. Und ohne die andere Extensions als Vorbild und Orientierungspunkte wären wir an vielen Stellen bei unserer eigenen Entwicklung anders oder falsch „abgebogen“. Also ein dickes „DANKE“ an dieser Stelle an die gesamte TYPO3 Community!
Vergleich der TYPO3 Restservice Extensions
Dokumentation
Der Disclaimer leitet wunderbar über zum ersten Punkt: Der Dokumentation. Da die Implementierung eines Restful Services in TYPO3 auf sehr unterschiedlich Arten lösbar ist, macht das eine gute und verständliche Dokumentation um so wichtiger.
EXT:rest
Ohne Frage: Die Doku von EXT:rest hat mit Abstand das schönste Bild auf der Seite 🙂 Als einzige der hier vorgestellten Extensions findet man die Doku auf einer eigenen Webseite, die Doku ist nicht im typischen TYPO3 Doku-Layout. Die Doku selbst beschränkt sich auf das Wesentliche: Die Installation und Konfiguration der Extension. Die Beispiele bewegen sich alle in TypoScript und PHP. Beispiele für die Requests werden auf der Kommandozeile (Terminal) und CURL gezeigt. Sehr positiv: Daniel Corn bietet einen eigenen Chat an, bei dem man Fragen zu der Extension stellen kann. Respekt an dieser Stelle, mit wieviel Geduld Daniel „Robert“ antwortet… puh.
EXT:t3api
Die Dokumentation zu der t3api des Teams von SourceBroker besticht auf den ersten Blick durch einen sehr strukturierten Aufbau, viele Schritt-für-Schritt Anleitungen und Beispiele, die sich per Copy & Paste übernehmen lassen. Leider ist die Doku aber noch an sehr vielen Stellen „Work-in-progress“ und in vielen entscheidenden Kapiteln dominiert der Satz „@todo – write docs“. Fazit: Ein guter Anfang. Wünschen wie dem Team die Zeit und Muße, die Doku zu Ende zu bringen.
EXT:nnrestapi
Die Dokumentation von nnrestapi hat nicht nur die mit Abstand umfangreichste Doku der hier vorgestellten TYPO3 Rest Api Extensions – sie zeigt als einzige Extension auch Full-Stack-Beispiel – von der Installation und Implementierung eines Endpoints in der eigenen Extension (PHP) bis zur exemplarischen Anbindung im Frontend in JavaScript – mit und ohne eine Library. Viele der Beispiele werden alternativ in VanillaJS, axios, jQuery angeboten. Und es gibt fast überall Links zu CodePen, um die Scripte zu testen. Für Lesefaule runden mehrere Videos die Doku ab. Fazit: In dieser Doku steckt eine Menge Liebe und der Wunsch, möglichst vielen Usern unter die Arme zu greifen – egal, aus welcher Ecke und mit welchem Vorwissen sie kommen.
EXT:restler
Knapp bis gar nicht vorhanden ist die Doku von EXT:restler. Die Entwickler von AOE haben dafür einen einfachen Grund: restler ist das PHP Framework eines Drittanbieters. Die TYPO3 Extension „EXT:restler“ verbindet das restler-Framework mit Extbase. Mit Ausnahme einiger knapper Beispiel, verweist die Extension auf die externe Doku von restler. Für Neueinsteiger stellt die Extension eine relativ steile Lernkurve dar. Man ist gezwungen, sich in restler einzuarbeiten und ist bei dem Transfer zu der Adaption in Extbase mehr oder weniger auf sich alleine gestellt. Fazit: Aller Anfang ist schwer. Und mancher verdammt schwer.
EXT:routes
Die Extension „YAML Routes“ hat eine schöne, verständliche Dokumentation im standardisierten TYPO3 Layout. Da – ähnlich wie bei der EXT:app_routes – der Funktionsumfang der Extension relativ knapp gehalten ist, hat man auch die Doku schnell bewältigt. Positiv hervorzuheben sind die vielen Beispiele und praktischen „Rezepte“. Fazit: Knapp und gut.
EXT:slimphp_bridge
Auf eine README.md beschränkt – aber durchaus ausreichend kommt die Extension „slimphp-bridge“ daher. Da diese Extension – ähnlich wie EXT:app_routes im Wesentlichen den Zweck verfolgt, per YAML das Routing zu einem Endpoint / Controller zu regeln, ist nicht viel Erklärung notwendig. Fazit: Wo nicht mehr ist, muss es nicht mehr sein.
EXT:app_routes
Die Doku von app_routes findet man nur als README.md des Github Repositories. Da die Konfigurationsmöglichkeiten der Extension sehr begrenzt sind, ist die einseitige Doku ausreichend. Fazit: Einfach zu verstehen – weil wenig zu verstehen.
EXT:sg_rest
Ebenfalls nur als README.md auf Github findet man die Doku der Extension sg_rest. Auf der längeren, einseitigen Doku findet man anpassbare Beispiele – leider ist die Struktur der Doku recht unübersichtlich und gleicht eher einer Kurzanleitung oder Merkhilfe, die „runtergeschrieben“ wurde. Fazit: Als Nachschlagewerk ist die Doku wenig geeignet, wird sie aber von oben nach unten „abgearbeitet“ ist sie durchaus brauchbar und hilft einem auf die Beine.
Einsatzmöglichkeiten der Extensions im Vergleich
Die Extensions verfolgen zum Teil sehr unterschiedliche Ansätze: Von einem simplen Routing – also dem „Verbinden“ einer URL mit der Klasse und Methode eines TYPO3 Controllers – bis zu einer umfangreichen Basis-Extension für die Entwicklung einer eigenen TYPO3 RESTful API mit komplexen Konfigurationsmöglichkeiten. Wir haben hier versucht, die Extension nach Typen zu clustern:
Routing-Extensions
Fokus der drei Extensions EXT:slimphp_bridge, EXT:routes und EXT:app_routes ist es, möglichst unkompliziert eine URL auf eine TYPO3 Klasse->Methode zu „mappen“. Dazu definiert man per YAML, TypoScript bzw. in der ext_localconf.php seiner Extension die URL-Pfade und gibt die Ziel-Methode an. Dabei fällt der Umfang der Funktionen recht unterschiedlich aus:
Hinter EXT:slimphp_bridge steckt kein geringerer als Benni Mack und das Team von b13. Die kleine Extension, die nur im github veröffenlicht wurde, versteht sich selbst nur als eine Art „Wrapper“, die das Routing vereinfachen soll – aber nie als „Headless Lösung“ gedacht war. Der Funktionsumfang bleibt entsprechend schlank. Per YAML kann ein Route-Prefix definiert werden (z.B. /api). Für alle Requests, die mit dem Prefix beginnen können dann Controller und Middlewares definiert werden und auf bestimmte Request-Methods (get, post, put, …). Ab dort ist man dann auf sich alleine gestellt: Die Extension kommt weder mit Methoden zum Authentifizieren von Usern – noch mit einer „out-of-the-box“-Lösung zum Generieren des Responses mit den entsprechenden Headern. Unter dem Strich also ein guter Ausgangspunkt, um schnell und einfach ein Routing zu definieren und eine solide Basis für alle, die ab dort ohnehin lieber „alleine“ unterwegs sind.
Die EXT:routes ist mit etwas mehr Konfigurationsmöglichkeiten (z.B. dem Filtern nach Request-Type im YAML) am Start – sie besticht aber im Vergleich zu slimphp_bridge vor allem durch eines: Der sehr umfangreicheren Beispiel-Sammlung in der Dokumentation. Der Einstieg fällt so auch einem Extbase-Neuling deutlich einfacher. Nach ein wenig Copy & Paste kann der eigene Endpoint an den Start gehen. Auch hier gilt: Fokus der Extenion war es nicht, eine Allround-Lösung zu bieten, sondern die ersten Stolpersteine beim Erstellen eines eigenen Routings aus dem Weg zu räumen. Ab dort kann die eigene Reise „ins Eingemachte“ gut beginnen…