Glossar der Begriffe

TL;DR:

• HTTP-Anfragen werden an JSON:API-Ressourcen gesendet. Verwechseln Sie diese nicht mit Resource Objects (Ressourcenobjekten).
• Das vom Client empfangene JSON-Objekt wird Dokument genannt.
• Ein Dokument ist immer ein JSON-Objekt und enthält die primären Daten unter einem data-Schlüssel.
• Die Daten unter diesem Schlüssel werden Resource Objects (Ressourcenobjekte) oder Resource Identifier Objects (Ressourcen-Identifikator-Objekte) genannt.
• Wenn Sie verlangen, dass verwandte Daten im Dokument eingebettet werden, handelt es sich um ein Compound Document (zusammengesetztes Dokument).
• Ein zusammengesetztes Dokument ist eines, das einen included-Schlüssel im obersten Objekt hat.
• Ressourcen, die viele Ressourcenobjekte zurückgeben, werden Collection Resources (Sammlungsressourcen) genannt.
• Ressourcen, die ein Ressourcenobjekt zurückgeben, werden Individual Resources (individuelle Ressourcen) genannt.
• Ressourcen, die Informationen über Beziehungen zwischen Ressourcenobjekten zurückgeben, heißen Relationship Resources (Beziehungsressourcen).
• In Drupal-Begriffen:
  • Resource Objects → Entitäten
  • Resource Identifier Objects → Feld-Items von Entitätsreferenzen
  • Document → JSON-Payload von Request/Response

Im Folgenden finden Sie eine kurze Beschreibung der Begriffe und Konzepte, die bei der Beschreibung des JSON:API-Moduls verwendet werden.

Dieses Glossar lehnt sich stark an die JSON:API-Spezifikation an, versucht jedoch, die Definitionen so darzustellen, wie sie auf Drupal zutreffen. Außerdem werden Feinheiten der Spezifikation erläutert, die für Einsteiger oder Leser ohne Erfahrung mit der Spezifikation oder dem Lesen von Spezifikationen möglicherweise nicht sofort ersichtlich sind.

Viele dieser Definitionen sind miteinander verknüpft. Ein Diagramm am Ende dieser Seite zeigt diese Begriffe im Kontext ihres Auftretens.

Ressource

Ein Ort, an dem ein JSON:API-Response Document abgerufen werden kann. Eine Ressource kann über ihre URL (Uniform Resource Locator) gefunden werden. Sie sollte nicht mit einem "Resource Object" verwechselt werden. Eine Ressource hat keine 1:1-Korrespondenz mit den Daten einer Anwendung.

In Drupal bedeutet dies, dass eine JSON:API-Ressource nicht mit einer Entität gleichzusetzen ist. Stattdessen ist eine Ressource ein Ort, an dem man Daten für ein Konzept abrufen kann. Zum Beispiel könnte dieses Konzept „eine Sammlung von Resource Objects des Typs node--article“ oder „eine Darstellung des Feldes field_tags (Entitätsreferenz) eines bestimmten Artikels“ sein.

Response Document

Der JSON-codierte Response-Body, der von einer JSON:API-Ressource zurückgegeben wird. Es ist der „Umschlag“, in dem Daten oder Fehler an den HTTP-Client kommuniziert werden. Es wird manchmal auch als Top-Level-Object bezeichnet. Wenn ein Dokument ein included-Document Member enthält, handelt es sich um ein Compound Document.

Compound Document

Ein Response Document, das ein included-Document Member enthält. Ein zusammengesetztes Dokument kann verwendet werden, um HTTP-Anfragen zu reduzieren, indem verwandte Resource Objects neben den primären Daten eines Response Documents eingebettet werden. Ein Compound Document kann angefordert werden, indem ein include-Query-Parameter zur Anfrage-URL hinzugefügt wird.

Error Document

Ein Response Document, das ein errors-Document Member enthält, welches ein oder mehrere Error Objects beinhaltet. Es enthält niemals ein data-Document Member. Der HTTP-Statuscode einer Antwort mit einem Error Document ist immer ein 4xx- oder 5xx-Code.

Individual Resource

Eine Ressource, die ein einziges Resource Object als data-Member im Response Document enthält. Mit ausreichender Berechtigung ist diese Ressource les- und schreibbar. In Drupal kann diese Ressource verwendet werden, um eine einzelne Entität zu „anzeigen“, „aktualisieren“ oder „löschen“. Sie kann nicht zum „Erstellen“ einer Entität verwendet werden.

Collection Resource

Eine Ressource, die viele Resource Objects als data-Member im Response Document enthält. Mit ausreichender Berechtigung ist diese Ressource lesbar und beschreibbar. Diese Ressourcen können paginierbar, filterbar und sortierbar sein. In Drupal kann diese Ressource zum „Erstellen“ einer neuen Entität verwendet werden. Sie kann nicht zum „Aktualisieren“ oder „Löschen“ von Entitäten in der Sammlung verwendet werden.

Relationship Resource

Eine Ressource, die ein Relationship Object als oberstes Objekt des Response Documents enthält. Sie enthält ein oder mehrere Resource Identifier Objects, die jeweils eine Referenz von einem Resource Object auf ein anderes darstellen. Mit ausreichender Berechtigung ist diese Ressource lesbar und änderbar. In Drupal kann diese Ressource verwendet werden, um die Items eines einzelnen Entity Reference-Feldes „anzuzeigen“ oder zu „bearbeiten“.

Related Resource

Eine Ressource, die eine spezielle Collection Resource ist, die ein oder mehrere Resource Objects als data-Member im Response Document enthält. Die Resource Objects in dieser Sammlung sind die Ziele einer Beziehung eines referenzierenden Resource Objects. Diese Ressource ist nur lesbar. In Drupal kann diese Ressource verwendet werden, um die von einem Entity Reference-Feld referenzierten Entitäten „anzuzeigen“, jedoch nicht, um diese Entitäten zu „aktualisieren“ oder das referenzierende Feld zu „bearbeiten“.

Document Member

Ein JSON-Objekt, das Teil des obersten JSON:API-Dokuments ist. Diese Objekte befinden sich immer im Dokument unter durch die Spezifikation festgelegten Schlüsseln (z.B. jsonapi, data, included oder errors).

Resource Object

Eine Darstellung einer Entität als JSON-Objekt. Sie sollte nicht mit einer "Ressource" verwechselt werden. Dieses hat eine 1:1-Korrespondenz mit den Daten der Anwendung.

Attributes Object

Ein JSON-Objekt, das Informationen über das Resource Object enthält, in dem es definiert ist. Attributes können jeden gültigen JSON-Wert enthalten. In Drupal stellt dieses Objekt alle Entitätsfeldwerte dar, die keine Entitätsreferenzen sind.

Relationships Object (Plural)

Ein JSON-Objekt, das Referenzen vom Resource Object, in dem es definiert ist, auf andere Resource Objects enthält. Es enthält viele Member, die Relationship Objects (Singular) sind. In Drupal stellt dieses Objekt alle Entity Reference-Feldwerte dar.

Relationship Object (Singular)

Ein JSON-Objekt, das die Referenzen vom Resource Object, in dem es definiert ist, auf andere Resource Objects darstellt. Es enthält Resource Identifier Objects, die jeweils eine einzelne Beziehung zu einem anderen Resource Object darstellen. In Drupal stellt dieses Objekt ein einzelnes Entity Reference-Feld dar.

Resource Identifier Object

Ein sehr einfaches JSON-Objekt, das eine Beziehung von einem Resource Object zu einem anderen darstellt. Es sollte nicht mit einem "Resource Object" verwechselt werden. Es enthält nur die Schlüssel type und id sowie optional meta, um Informationen über diese Beziehung zu speichern. Bemerkenswert ist, dass es kein links-Member enthält.

Es bietet das sogenannte „Resource Linkage“, welches in einem