Die neue Web Services API von Joomla! 4 erschliesst dir eine ganze Reihe von externen Diensten, die du in Joomla! einbinden kannst.
Dieser Web Service ermöglicht deiner Website über die API-Schnittstelle mit anderen Websites zu kommunizieren. Das bietet dir soviel Möglichkeiten, dass es deine Vorstellungen sprengt. Zum Beispiel:
- Du kannst die Web Services API nutzen, um Artikel und Inhalte zwischen verschiedenen Websites in einem Netzwerk auszutauschen. So kannst du zum Beispiel an einem zentralen Ort deine eigenen kundenspezifischen Hilfeseiten erstellen, um sie dann via die Webservice-API auf alle die Kunden-Websites ausrollen.
- Du kannst die Webservice-API zum Verbinden einer externen Datenquelle verwenden, wie z.B. einem Immobilienverzeichnis mit einer eigenen API, die dann via die Joomla! Webservice-API auf deine Joomla!-Seite eingebunden werden kann.
- Man kann die Webservice-API zum Einbinden von Bannerwerbung im Website-Netzwerk verwenden und die Rapporte und Rechnungen direkt in Xero integrieren.
- Wenn die Datenverteilung dein Ding ist, könnte die Webservice-API sogar als Daten-Lieferant für ein Headless CMS eingesetzt werden.
- Beim diesjährigen JandBeyond hat Carlos Cámara Mora die Web Services erklärt. Anhand einer Demo zeigte er, wie man in Joomla! 4 mithilfe der der Web Services API und Flutter mobile Applikationen bauen kann.
- Wenn man noch weiter über den Tellerrand hinausschaut, könnte man die Webservice-API sogar zur Verwaltung von IoT-Geräten (Geräte übers Internet steuern) verwenden. Ein einfaches Beispiel wäre, wenn ein Artikel auf der Website eine bestimmte Anzahl Klicks einreicht, dass dann deine Philipps Hue Birne die Farbe wechselt.
- Die Londoner JUG hat an ihrem Juni Treffen sich sehr ausführlich damit befasst. Du kannst dir den Workshop auf YouTube ansehen. Der Link führt dich direkt an die Stelle, wo gezeigt wird, wie man Beiträge zwischen einer Joomla! 3- und einer Joomla! 4-Website hin- und herschieben kann.
In diesem Artikel geben wir dir ein paar wichtige Tipps, was du zum Einrichten und Verwenden der Webservice-API in Joomla! 4 wissen musst.
Diese Artikelserie soll jeden zweiten Monat bis ins Jahr 2021 fortgesetzt werden, mit dem Ziel zu zeigen, wie man die Joomla! Web Services API im Detail verwenden könnte. Wenn du selbst gute Ideen für einen Artikel oder sogar ein eigenes Webservice Anwendungsbeispiel hast, dann melde dich bei uns. Wir würden gerne etwas darüber schreiben.
Werbung
Die Web Service API Endpoints
Die Liste der Joomla Core API Endpunkte deckt alle wichtigen Kernfunktionen von Joomla! ab. Wenn du mal durch die Liste scrollst, wirst du verstehen, wie du API-Aufrufe einsetzen kannst, um deine Joomla-Daten zu nutzen oder sie auf verschiedenen Arten wieder zurückzugeben.
Jeder URL-Aufruf erfordert eine Authentifizierung. Es sei denn, es handelt sich um eine öffentliche URL. Weil die API-Anwendung brandneu ist, benötigt sie für die Sicherheit in Joomla 4.0.0 mindestens einen Super-Admin API Token. Dies kann später noch herabgestuft werden, wenn die API stabil läuft und sie in der Community ausgiebig getestet ist.
Der neue Webservices-Plugin-Typ ermöglicht es den Entwicklern, ihre Erweiterungen so auszubauen, dass sie die Joomla 4 Web Services API auch nutzen können. Ein Beispiel dafür, wie das mit der Weblinks-Komponente umgesetzt wurde, findest du in der Joomla-Dokumentation.
Der Joomla! Super Admin API Token
Die Web Services API wird sich zusammen mit Joomla! 4 Zweig weiterentwickeln. Im Moment ist der Zugriff aber auf die Integration auf die Super Admin Rolle beschränkt.
So kannst du deinen Joomla API Token für die Nutzung der neuen Web Services API aktivieren:
- Melde dich in dein Joomla! 4 Administrations-Backend als Super Admin an
- Gehe zum Benutzermenü (oben rechts auf dem Bildschirm)
- Wähle den Menüpunkt: Konto bearbeiten
- Klicke auf die Registerkarte: Joomla-Token
Hier kannst du den Token kopieren, sowie ihn aktivieren oder deaktivieren und zurücksetzen. Wenn du den Zugriff widerrufen und einen neuen Token generieren musst, sei dir bewusst, dass alle Orte, an denen der Token verwendet wurde, nicht mehr funktionieren werden. Du musst dann alle Token auf den neuen Wert aktualisieren.
Du kannst den Token auch über das Menü: Benutzer > Verwalten bearbeiten. Auch wenn du die Token der anderen Benutzer selbst nicht siehst, kannst du sie trotzdem aktivieren, deaktivieren oder zurücksetzen. z.B. wenn der Verdacht besteht, dass der Token in fremde Hände gelangt ist.
Um im nächsten Abschnitt dieses Artikels den Postman-Service einzurichten, benötigst du den Joomla-API-Token. Lasse die Registerkarte offen, um später den Token kopieren zu können, wenn du die Authentifizierung in Postman einrichtest.
Wie man die Web Service API Endpoints testet
In Anwendungs-Alltag werden API-Endpoints in der Regel auf Serverebene mit CURL aufgerufen oder in andere Programmieraufrufe eingebettet. Wenn du selber ein Web-Service-fähiges Tool erstellen willst, ist es hilfreich, wenn man selber Testen kann, ob die angeforderten Daten auch am anderen Ende ankommen.
Für den Test der Endpoints gibt es eine ganze Reihe an Tools:
- Mit CURL können die API-Aufrufe über eine Befehlszeile getestet werden.
- Um die RESTful-Webservices zu testen, kann man Programme wie PHP Storm verwenden.
- Es gibt auch ein Tool namens Postman, das speziell zum Testen von APIs entwickelt wurde.
Heute werden wir dir das Postman-Tool zeigen. Alexandre Elises hat auf GitHub eine Zusammenstellung der wichtigsten Postman Routinen zum Testen der Joomla 4 API Endpoints bereitgestellt. Diese handliche JSON-Datei deckt alle aktuellen Endpunkte ab und wird laufend aktualisiert, wenn weitere API Endpoints hinzukommen werden.
- Als Erstes musst du das Postman-Programm herunterladen und Installieren.
- Lade dir als Nächstes die Postman Collection of Joomla 4 API Endpoints von GitHub herunter. Die Anleitung, wie du die Sammlung in Postman importieren musst, findest du direkt in der heruntergeladenen Datei.
- Nachdem du die Sammlung installiert hast, musst du die Einstellungen anpassen und deinen Joomla-API-Token auf der Registerkarte „Autorisierung“ einfügen.
- Anschliessend gehst du zur Registerkarte Variablen und aktualisierst die Variable base_path, um auf deine Joomla 4-Website zu verlinken.
- Um zu testen, ob die Endpunkte eine Verbindung zur Website herstellen können, verwende einen der GET-Endpunkte.
Wenn du eine gültige Rückmeldung bekommen hast, ist die Einrichtung abgeschlossen und du kannst mit den eigenen Test-Abfragen in Postman beginnen. Solltest du eine Verboten-Meldung (403) erhalten, musst du nochmals deine Einstellungen überprüfen. Vor allem der API-Token auf der Registerkarte Autorisierung muss der Schlüsselwert auf X-Joomla-Token gesetzt sein.
Der Anwendungs-Test
Jetzt, wo du Postman richtig konfiguriert hast, gibt es mehrere Ebenen der Webservice-API. Wir werden hier nicht im Detail auf das Erlernen des Postmanns eingehen, es gibt eine umfassende Sammlung, die dir dabei hilft.
Bei den RESTful Services wie der Joomla Web Services API gibt es 5 Arten von HTTP-Methoden, die typischerweise beim Ausführen von Befehlen verwendet werden. Hier sind einige Beispiele dafür, wie du jeder dieser Methoden verwenden kannst.
POST – Wird zum Erstellen eines neuen Datensatzes unter Verwendung des Ziel-Endpunkts verwendet
- Erstelle einen neuen Artikel oder eine neue Kategorie mit Hilfe der API
- Erstelle eine neue Banneranzeige, wenn ein Datensatz in einem Werbemanagementtool erstellt wird
- Einen neuer Templatestil erstellen
- Einen neuen Benutzer auf der Website anlegen
Damit die POST-Methoden richtig funktionieren, muss für die Befüllung der Datenbank eine eigene JSON-Zeichenfolge mit den nötigen Informationen bereitstellen. Dies wird der Schwerpunkt des nächsten JCM-Artikels sein.
GET – Daten von der Joomla-Site über einen bestimmten Endpunkt abrufen
- Abfrage einer Liste von Artikeln auf der Website
- Einen bestimmten Artikel von einer Website abfragen
- Abfrage einer Liste der auf der Website verwendeten Tags (Schlagwörter)
- Abfrage einer Liste der Weiterleitungen auf der Website
- Durch Hinzufügen von Variablen zu Abfragen können man sich auf die Endpunktanforderungen konzentrieren, um nach einem bestimmten Datensatz zu filtern. Wenn du z.B. einen Wert hinzufügst, der {{{article_id}} in einem Endpunkt für Artikel ersetzt, kannst du nur die Informationen für einen einzelnen Artikel anstelle einer gesamten Artikelliste zurückgeben.
GET-Methoden sind in Postman am einfachsten zu testen, da sie Daten von den Endpunkten abrufen, und du kannst die JSON-Daten für das zurückgegebene Ergebnis direkt in Postman sehen.
PUT – Daten wieder in einen Endpunkt einfügen
PUT-Methoden sind deswegen gefährlich, weil sie den Datensatz in der Datenbank aktualisieren, indem sie ihn durch einen neuen Datensatz ersetzen. Gegenwärtig hat die Joomla 4 Web Services API keine PUT-Endpunkte, sondern verwendet stattdessen PATCH, das zur Aktualisierung und Änderung von Datensätzen verwendet wird.
PATCH – Daten über einen Endpunkt modifizieren
- Ändere einen Banner-Eintrag, um das ursprüngliche Veröffentlichungsdatum oder den Veröffentlichungsstatus zu ändern, wenn die Anzeigeverwaltung unterbrochen werden muss und die Anzeige vorübergehend nicht läuft.
- Passe den Datensatz eines Benutzers an, um seine ACL dynamisch zu aktualisieren, wenn seine Rolle im HR-System des Unternehmens geändert hat.
- Passe die Attribute der Menüpunkte an
- Passe die Sprach-Overrides an, um saisonale Begrüssungen an die Website Besucher auszugeben
PATCH-Endpunkte sind flexibler als PUT-Endpunkte. Bei PUT muss der gesamte Datensatz neu in die Datenbank geschrieben werden, während bei einem PATCH-Endpunkt nur die spezifischen Felder eines Datensatzes aktualisiert wird.
DELETE – Löschen von Daten über einen Endpunkt
- Lösche einen Kontakt, wenn er das Unternehmen verlässt.
- Lösche ein Sprach-Override, wenn es nicht mehr benötigt wird
- Lösche einen Templatestil
- Lösche einen nicht mehr benötigten Tag
DELETE-Endpunkte müssen mit Vorsicht verwendet werden, da sie Daten aus der Datenbank löschen! Wenn du stattdessen einen Artikel in den Papierkorb verschieben möchtest, verwende dafür den PATCH-Endpunkt.
Mit diesen fünf HTTP-Methoden im Hinterkopf kannst du einen Blick durch die 111 verfügbaren Endpunkte (zum Zeitpunkt der Veröffentlichung) werfen und sehen, welche du für deine eigenen Projekte verwenden könntest. Wenn dir selber etwas Gutes einfällt, kommentiere es unten. Vielleicht können wir das in einem künftigen Artikel des Joomla Community Magazins aufnehmen, was du mit der neuen Joomla 4 Web Services API gemacht hast.
Werbung
Weitere Quellen
Solltest du früher anfangen wollen, findest du nachfolgend eine Reihe von Unterlagen, die dir dabei helfen könnten:
- Joomla! API-Dokumentation
- Joomla 4 API-Sammlung – Alexandre Elise
- JoomDev – Joomla 4 API Einführung (November 2019)
- Joomla API Code Along Workshop – Joomla Usergruppe (JUG) London – Juni 2020
- Mit Joomla API & Google Flutter mobile Anwendungen erstellen – Carlos Cámara Mora – JandBeyond May 2020
Quelle: Joomla Magazin – Ausgabe: August 2020 geschrieben von Patrick Jackson
2 Antworten
Sehr schöner Artikel.
Hallo,
wie bekomme ich denn über API Daten EINGELESEN ?
Ich habe zb ein externen Shop, der eine API ausgeben kann.
Ich hätte gerne die im Shop eingetragenen Nutzerdaten auch an mein Joomla übertragen (Nutzername, Name, Passwort, das der Kunde sich bei mir nicht 2x abmelden muß.