Joomla Api Specification/de: Difference between revisions

Latest revision as of 20:55, 22 September 2021

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.

@@ Line 2: / Line 2: @@
 <noinclude>{{Joomla version|version=4.0}}</noinclude>
-This page is intended to reflect the Specification of the Joomla API. This will be updated and reflect the latest version of Joomla at all times
+Diese Seite soll die Spezifikation der Joomla Webservices-API beschreiben. Sie wird laufend aktualisiert und berücksichtigt jederzeit die neueste Version von Joomla.
-== Authentication ==
+== Authentifizierung ==
-There is a group of api-authentication plugins to allow custom authentication into Joomla Core which can have any implementation. We have chosen not to implement a full blown oAuth 2 specification into the core however it is intended that this can be achieved with the plugin group (and by disabling the "API Authentication - Joomla Token" plugin and the "User - Joomla Token" plugin. The built in authentication uses a Bearer Token implementation.
+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.
-The hmac is the main security feature of our Bearer token implementation. This is the [https://tools.ietf.org/html/rfc2104 RFC 2104] HMAC of the seed data using Joomla's site secret (the $secret in configuration.php) as the key. The base64 encoded seed is stored in the database in the user profile table of the database.
+Der hmac ist das wichtigste Sicherheitsmerkmal unserer Bearer-Token-Implementierung. Dabei handelt es sich um den [https://tools.ietf.org/html/rfc2104 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.
-The token itself is the base64-encoded representation of a string algorithm:user_id:hmac. The algorithm tells us which cryptographic hash function was used to generate the HMAC. Per the security considerations of [https://tools.ietf.org/html/rfc6151 RFC 6151] we forbid the use of the less secure cryptographic hash functions. In fact, the current implementation only allows SHA-256 and SHA-512 with SHA-256 being the (hardcoded) method used to generate the token displayed to the user. (i.e. SHA-512 is added for forward compatibility).
+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 [https://tools.ietf.org/html/rfc6151 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).
-For security and privacy reasons users can only view their own token, even if they are Super Users. Users with com_users edit privileges can also disable, enable or reset another user's token (if they believe the token has been compromised) BUT they still cannot view it. Users can also choose to disable their own API Key.
+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.
-There is also a legacy basic authentication plugin for simple local development however this is likely to be removed before the release of Joomla 4.0.0 stable.
+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 by default will return JSON API Responses when requested with a <source lang="html" inline>Accepts: application/json</source> header as well as with the specific JSON API header. Joomla will support the ability to add additional content types that can be responded. System plugins adding this mapping will be responsible for ensuring that components support this mapping. Core Joomla will not support additional content types.
+Joomla gibt standardmäßig JSON-API-Antworten zurück, wenn sie mit einem <source lang="html" inline>Accept: application/json</source> 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.
-=== Language Negotiation ===
-Currently language negotiation is not supported. However we open to adding support for this in the future.
+=== Sprachvereinbarung (Language Negotiation) ===
+Derzeit werden Sprachvereinbarungen nicht unterstützt. Wir sind jedoch offen dafür, in Zukunft weitere Unterstützung dafür anzubieten.
 === Routing ===
-==== Basic Information ====
+==== Basis-Information ====
-Joomla CMS needs to use a separate Router for the API as the API will be strictly RESTful (i.e. a POST and GET request to the same URL will give different outcomes). For this we will therefore use the Joomla Framework router which is already restful and then map requests to it to JInput variables so that similar JInput data is populated to that in the Joomla Web Interfaces.
+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 <tt>/api</tt> auf der Joomla-URL beginnen. Das kann nicht angepasst werden, es sei denn, Sie beschließen, die Speicherorte der Ordner mit einer benutzerdefinierten <tt>includes/defines.php</tt> Datei in allen Ebenen des CMS umzuschreiben (tun Sie dies auf eigenes Risiko und erwarten Sie nicht viel bzw. keine Unterstützung!).
-As Joomla's API lives in the api folder of Joomla all routes will start with <tt>/api</tt> on the root Joomla URL. This is not customisable unless you decide to rewrite folder locations with a custom <tt>includes/defines.php</tt> files in all levels of the CMS (do this entirely at your own risk and don't expect much/any support!)
-==== Adding Routes ====
+==== Routen hinzufügen ====
-Routes are registered through plugins with type webservice. A plugin can add one or more routes (each should be aware of it's RESTful type). Whilst puristically 1 plugin per content type would be better, there is also a tradeoff between number of plugins installed on your Joomla site for management. Therefore we recommend a plugin per component to expose admin data and then if you are coding in extra routes an extra plugin (of course this is just a recommendation - use cases of course vary!)
+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).
-== Responses ==
+== Antworten ==
-=== API Response Format ===
+=== API Antwortformat ===
-Joomla evaluated several response API Formats including JSON-LD, JSON API and Collection+JSON. For a more detailed evaluation you can look [https://joomla-projects.github.io/gsoc19_webservices/?specification/chapters/json-response-formats.md at this summary document] produced as part of our GSOC 2017 project. We have settled on using the JSON API v1.0 specification (at the time of producing the JSON API 1.1 which recently became release candidate had no major libraries implementing it and appeared stuck).
+Joomla hat verschiedene Response-API-Formate untersucht, darunter JSON-LD, JSON API und Collection+JSON. Eine detailliertere Auswertung finden Sie in diesem [https://joomla-projects.github.io/gsoc19_webservices/?specification/chapters/json-response-formats.md 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.
-The JSON API v1.0 specification can be found on [https://jsonapi.org/format/ the json api website].
+Die JSON API v1.0-Spezifikation finden Sie auf der [https://jsonapi.org/format/ JSON API Website].
-Some batch interactions in the Joomla API will also use the JSON API Partial Success module for error handling which can be found [https://gist.github.com/e0ipso/732712c3e573a6af1d83b25b9f0269c8/ in this gist].
+Einige Batch Interaktionen in der Joomla API verwenden auch das JSON API Partial Success Modul zur Fehlerkontrolle, das [https://gist.github.com/e0ipso/732712c3e573a6af1d83b25b9f0269c8/ in diesem Gist] zu finden ist.
-=== Richardson Maturity Model and Hypermedia ===
+=== Richardson Reifegrad-Modell und Hypermedia ===
-We expect Joomla to largely comply with Level 3 of the Richardson Maturity Model. If you want to read about what this means we recommend looking at the [https://martinfowler.com/articles/richardsonMaturityModel.html|Martin Fowler page] on it. Our entity systems (JTable and JModel) aren't ideally suited for this which means in some places especially around data relations there's likely to be some implementation difficulties
+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 [https://martinfowler.com/articles/richardsonMaturityModel.html|Martin 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.
 <noinclude>
 [[Category:Development{{#translation:}}]]
-[[Category:Joomla!_Api{{#translation:}}]]
+[[Category:Joomla! 4.x Web Services{{#translation:}}]]
 [[Category:Joomla!_4.x{{#translation:}}]]
 </noinclude>