Joomla! Documentation™

Joomla! 

4.0

Diese Seite soll die Spezifikation der Joomla Webservices-API beschreiben. Sie wird laufend aktualisiert und berücksichtigt jederzeit die neueste Version von Joomla.

Authentifizierung

Es gibt eine Gruppe von api-Authentifizierungs-Plugins, um eine benutzerdefinierte Anmeldung in Joomla Core zu ermöglichen. Diese können mit einer beliebige Anwendung realisiert sein. Wir haben uns dafür entschieden, keine vollständige oAuth-2 Spezifikation in den Core zu implementieren, aber es ist beabsichtigt, dass dies mit der Plugin-Gruppe (bei gleichzeitiger Deaktivierung des „API-Authentifizierung - Joomla Token“ Plugins und des „Benutzer - Joomla Token“ Plugins) erreicht werden kann. Die eingebaute Authentifizierung verwendet eine Bearer-Token-Implementierung.

Der hmac ist das wichtigste Sicherheitsmerkmal unserer Bearer-Token-Implementierung. Dabei handelt es sich um den RFC 2104 HMAC der Startdaten mit dem Joomla-Site-Secret, das $secret in der configuration.php, als Schlüssel. Der base64-kodierte Seed wird in der Benutzerprofil-Tabelle der Datenbank gespeichert.

Das Token selbst ist die base64-kodierte Darstellung eines String-Algorithmus: user_id:hmac. Der Algorithmus sagt uns, welche kryptographische Hash-Funktion zur Erzeugung des HMAC verwendet wurde. Gemäß den Sicherheitsüberlegungen von RFC 6151 verbieten wir die Verwendung der weniger sicheren kryptographischen Hash-Funktionen. Tatsächlich erlaubt die aktuelle Implementierung nur SHA-256 und SHA-512, wobei SHA-256 die (hartkodierte) Methode ist, die zur Erzeugung des dem Benutzer angezeigten Token verwendet wird. (d.h. SHA-512 wird aus Gründen der Vorwärtskompatibilität hinzugefügt).

Aus Sicherheits- und Datenschutzgründen können Benutzer nur ihr eigenes Token sehen, auch wenn sie Superuser sind. Benutzer mit com_users-Bearbeitungsberechtigungen können auch das Token eines anderen Benutzers deaktivieren, aktivieren oder zurücksetzen (wenn sie glauben, dass das Token kompromittiert wurde), aber sie können es trotzdem nicht sehen. Benutzer können auch ihren eigenen API-Schlüssel deaktivieren.

Es gibt auch noch ein vererbtes Basis-Authentifizierungs-Plugin für eine einfache lokale Entwicklung, jedoch wird dieses wahrscheinlich vor der Veröffentlichung der stabilen Version Joomla 4.0.0 entfernt werden.

Requests

Content Negotiation

Joomla gibt standardmäßig JSON-API-Antworten zurück, wenn sie mit einem Accept: application/json Header sowie mit dem spezifischen JSON-API-Header angefordert werden. Joomla wird die Fähigkeit unterstützen, zusätzliche Inhaltstypen einzufügen, auf die geantwortet werden kann. System-Plugins mit diesen Mappings werden dafür selbst verantwortlich sein, dass die Komponenten dieses Mapping unterstützen. Der Joomla! Kern wird keine zusätzlichen Inhaltstypen unterstützen.

Sprachvereinbarung (Language Negotiation)

Derzeit werden Sprachvereinbarungen nicht unterstützt. Wir sind jedoch offen dafür, in Zukunft weitere Unterstützung dafür anzubieten.

Routing

Basis-Information

Joomla CMS muss einen separaten Router für die API verwenden, da die API strikt RESTful sein wird (d.h. eine POST- und GET-Anfrage an dieselbe URL führt zu unterschiedlichen Ergebnissen). Deshalb werden wir dafür den Joomla-Framework-Router verwenden, der bereits RESTful ist. Dann werden wir Anfragen an diesen Router auf JInput-Variablen abbilden, sodass ähnliche JInput-Daten mit denen in den Joomla-Web-Interfaces aufgefüllt werden.

Da die Joomla API im api-Verzeichnis gespeichert ist, werden alle Routen mit /api auf der Joomla-URL beginnen. Das kann nicht angepasst werden, es sei denn, Sie beschließen, die Speicherorte der Ordner mit einer benutzerdefinierten includes/defines.php Datei in allen Ebenen des CMS umzuschreiben (tun Sie dies auf eigenes Risiko und erwarten Sie nicht viel bzw. keine Unterstützung!).

Routen hinzufügen

Die Routen werden durch Plugins vom Typ Webservice registriert. Ein Plugin kann eine oder mehrere Routen hinzufügen (jedes Plugin sollte seinen RESTful-Typ kennen). Während puristisch gesehen 1 Plugin pro Inhaltstyp besser wäre, gibt es einen Kompromiss bei der Anzahl der auf der Joomla-Site installierten Verwaltungs-Plugins. Daher empfehlen wir ein Plugin pro Komponente, um die Verwaltungs-Daten freizugeben. Wenn Sie zusätzliche Routen anlegen, empfehlen wir ein zusätzliches Plugin (dies ist natürlich nur eine Empfehlung - die Einsatzfälle können natürlich variieren).

Antworten

API Antwortformat

Joomla hat verschiedene Response-API-Formate untersucht, darunter JSON-LD, JSON API und Collection+JSON. Eine detailliertere Auswertung finden Sie in diesem zusammenfassenden Dokument, das im Rahmen unseres GSOC 2017-Projekts erstellt wurde. Wir haben uns auf die Verwendung der JSON API v1.0-Spezifikation geeinigt, da zum Produktions-Zeitpunkt in der JSON API 1.1, die kürzlich zum Release Candidate erhoben wurde, keine wesentlichen Bibliotheken implementiert waren und offenbar nicht weiterkam.

Die JSON API v1.0-Spezifikation finden Sie auf der JSON API Website.

Einige Batch Interaktionen in der Joomla API verwenden auch das JSON API Partial Success Modul zur Fehlerkontrolle, das in diesem Gist zu finden ist.

Richardson Reifegrad-Modell und Hypermedia

Wir gehen davon aus, dass Joomla weitgehend der Stufe 3 des Richardson Reifegrad-Modells entspricht. Wenn Sie sich darüber informieren möchten, was damit gemeint ist, empfehlen wir Ihnen, einen Blick auf die Fowler-Seite zu werfen. Unsere Entity-Systeme (JTable und JModel) sind dafür nicht ideal geeignet, sodass es an einigen Stellen, insbesondere im Bereich der Datenrelationen, vermutlich ein paar Probleme bei der Implementierung geben wird.