JSON:API-Backend

Die JsonDrop API verwendet die JSON:API-Implementierung für die Interaktion zwischen Backend und Frontend und ist vollständig konform mit der:

JSON:API-Spezifikation

Postman-Collection mit sofort einsatzbereiten Endpunkten:

https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link

In den eigenen Worten der JSON:API-Spezifikation:

[Eine] Spezifikation, wie ein Client anfordern soll, dass Ressourcen abgerufen oder verändert werden, und wie ein Server auf diese Anfragen reagieren soll.

JSON:API ist darauf ausgelegt, sowohl die Anzahl der Anfragen als auch die Menge der übertragenen Daten zwischen Client und Server zu minimieren. Diese Effizienz wird erreicht, ohne Lesbarkeit, Flexibilität oder Auffindbarkeit zu beeinträchtigen.

Drupals Datenstrukturen, also Entitätstypen, Bundles und Felder, eignen sich hervorragend für die Nutzung mit JSON:API.

Durch die Aktivierung des JSON:API-Moduls erhalten Sie sofort eine vollständige REST-API für jeden Typ in Ihrer Drupal-Anwendung. JSON:API analysiert Ihre Entitätstypen und Bundles, sodass dynamisch URLs bereitgestellt werden, über die Sie auf jede einzelne Entität mit den Standard-HTTP-Methoden GET, POST, PATCH und DELETE zugreifen können.

JSON:API folgt dem Prinzip, dass das Modul „out of the box“ produktionsbereit ist. Das bedeutet, das Modul ist sehr festgelegt darin, wo Ressourcen liegen, welche Methoden sofort verfügbar sind, und überlässt die Zugriffskontrolle dem Berechtigungssystem von Drupal Core. Aktuell gibt es keine eigenen Konfigurationsseiten – Sie können also mit minimalem Aufwand eine API-gesteuerte Drupal-Anwendung starten.

Die Unterseiten dieser Dokumentation behandeln:

• Kernkonzepte der JSON:API-Spezifikation – und deren Anwendung in Drupal
• Einen allgemeinen Überblick über die von diesem Modul bereitgestellte API
• Praktische Informationen zum Aufbau Ihrer HTTP-Anfragen
• Wie Sie Ihre Anfragen authentifizieren
• Häufige Stolpersteine
• Spezifische Dokumentation zu:
  • Einzelne Ressourcen abrufen (GET)
  • Sammlungen von Ressourcen abrufen (GET mit Filtern, Paginierung und Sortierung)
  • Neue Ressourcen erstellen (POST)
  • Bestehende Ressourcen aktualisieren (PATCH)
  • Bestehende Ressourcen löschen (DELETE)

Bei spezifischen Fragen erstellen Sie bitte eine Support-Anfrage im JSON:API-Issue-Queue [480 Issues].

Die von JSON:API bereitgestellte API dreht sich um Drupals Entitätstypen und Bundles. Jedes Bundle erhält einen eigenen eindeutigen URL-Pfad, der einem gemeinsamen Muster folgt.

Im Gegensatz zum REST-Modul von Drupal Core sind diese Pfade nicht konfigurierbar und standardmäßig alle aktiviert. Im Unterschied zu Core REST ist JSON:API nicht einfach nur ein weiteres Format wie JSON oder HAL+JSON, sondern umfasst eine viel größere Menge von Regeln, wie Ihre API funktionieren soll. Es legt fest, welche HTTP-Methoden verwendet werden, welche HTTP-Statuscodes unter bestimmten Umständen zurückgegeben werden, das Format des Response-Bodys und die Verknüpfung zwischen Ressourcen. Für einen detaillierten Vergleich siehe JSON:API vs. Core’s REST module.

Typen

Jede Ressource in JSON:API muss eine global eindeutige type-Eigenschaft besitzen. Die Drupal-JSON:API-Implementierung leitet diesen Typ aus dem maschinenlesbaren Namen des Entitätstyps und des Bundles ab. Beispiele: Artikel, Seiten und Benutzer erhalten die Typen node--article, node--pages und user--user. Beachten Sie, dass der Benutzer-Entitätstyp in Drupal kein Bundle hat. Ist kein Bundle vorhanden, wird der Entitätstyp für die Konsistenz einfach wiederholt.

URL-Struktur

Eine JSON:API-URL sieht wie folgt aus:

GET|POST     /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

Jeder Ressourcentyp muss in der API eindeutig adressierbar sein. Das bedeutet, dass jeder Typ, der in der API verfügbar ist, eine eindeutige URL haben muss. Es kann immer nur ein Ressourcentyp über eine bestimmte URL abgerufen werden. Die Drupal-Implementierung folgt dem Muster: /jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}].

Die URL ist immer mit /jsonapi vorangestellt.

Danach werden Entitätstyp-ID und Bundle-ID durch einen Schrägstrich verbunden. Beachten Sie, dass es keine URL /jsonapi/node gibt, da dies gegen die Spezifikation verstoßen würde, weil darüber mehrere Ressourcentypen erreichbar wären.

Vorhanden:
	/jsonapi/node/page
	/jsonapi/node/article

Nicht vorhanden:
	/jsonapi/node

Nach Entitätstyp und Bundle-ID folgt optional ein ID-Teil. Zum gezielten Ansprechen einer einzelnen Ressource – etwa zum Abrufen, Aktualisieren oder Löschen – muss dieser Teil vorhanden sein. Dabei handelt es sich immer um die UUID der Ressource. Beim Erstellen einer neuen Ressource oder beim Abrufen einer Sammlung eines Typs lässt man den ID-Teil weg.

GET, POST
/jsonapi/node/article

PATCH, DELETE
/jsonapi/node/article/{uuid}

HTTP-Methoden

Die JSON:API gibt vor, welche HTTP-Methoden akzeptiert werden. Diese sind: GET, POST, PATCH und DELETE. Bemerkenswert: PUT ist nicht enthalten.

• GET – Daten abrufen (Sammlung oder einzelne Ressource)
• POST – Neue Ressource erstellen
• PATCH – Bestehende Ressource aktualisieren
• DELETE – Bestehende Ressource löschen

Request-Headers

Stellen Sie sicher, dass Sie „Content-Type“ und „Accept“-Header richtig verwenden. Siehe Client responsibility für Details.

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Response Codes

Die JSON:API-Spezifikation gibt außerdem erlaubte Antwortcodes vor. Die Drupal-Implementierung nutzt eine Teilmenge davon. Das Modul kann folgende Codes zurückgeben:

• 200 OK – Alle erfolgreichen GET- und PATCH-Anfragen
• 201 Created – Alle erfolgreichen POST-Anfragen (Antwort enthält die neue Ressource)
• 204 No Content – Alle erfolgreichen DELETE-Anfragen

Artikel aus der Drupal-Dokumentation.