Überarbeitungen

Das JSON:API-Modul stellt Entitätsrevisionen als Ressourcenversionen zur Verfügung, inspiriert von RFC5829: Link Relation Types for Simple Version Navigation between Web Resources.

Aktuelle Einschränkungen:

• Ressourcenversionen (Entitätsrevisionen) können nur gelesen werden. Und nur für die Entitätstypen Node und Media (node--* und media--* Ressourcentypen) kann JSON:API die Ressourcenversionen zugänglich machen (aufgrund des Fehlens einer formalen Zugriffskontrolle für Entitätsrevisionen in Drupal Core; sobald dies verfügbar ist, werden wir alle revisionierbaren Entitätstypen über JSON:API verfügbar machen, siehe #3031271: Support version negotiation for any entity type (currently only Node & Media are supported)).
• Ressourcenversionen werden jedoch automatisch erstellt, wenn eine Ressource eines Ressourcentyps (Entitätstyp + Bundle), der so konfiguriert ist, dass automatisch neue Versionen (Revisionen) erstellt werden, per PATCH geändert wird. Es ist geplant, es zu ermöglichen, bei einer PATCH-Anfrage an eine versionierbare Ressource anzugeben, ob eine neue Revision erstellt werden soll oder nicht (#2993557: Allow optional creation of new revision when PATCHing revisionable entities to support autosave functionality via JSON:API.).

Die Unterstützung von Revisionen ist kein offizieller Bestandteil der JSON:API-Spezifikation. Es werden jedoch verschiedene „Profiles“ entwickelt (ebenfalls nicht offiziell Teil der Spezifikation, aber bereits in JSON:API v1.1 aufgenommen), um alle von JSON:API entwickelten benutzerdefinierten Funktionen zu standardisieren (die weiterhin mit der Spezifikation konform sind).

Auf diese Weise sollte das JSON:API-Modul maximal kompatibel mit anderen Systemen sein und die „Drupalisms“, die ein Entwickler beim Arbeiten mit einer JSON:API-Implementierung kennen muss, auf ein Minimum reduzieren.

Eine „Version“ im JSON:API-Modul ist jede Revision, die zuvor oder aktuell eine Standardrevision war. Nicht alle Revisionen gelten als „Version“. Revisionen, die nicht als „Standard“-Revision markiert sind, gelten als „Arbeitskopien“, da sie normalerweise nicht öffentlich verfügbar sind und die Revisionen sind, an denen die meisten neuen Arbeiten vorgenommen werden.

Wenn das Content Moderation-Modul installiert ist, ist es möglich, dass die aktuellste Standardrevision nicht die neueste Revision ist.

Das Anfordern einer Ressourcenversion erfolgt über einen URL-Query-Parameter. Dieser hat folgendes Format:

            version-identifier
                  __|__
                 /     \
?resourceVersion=foo:bar
                 \_/ \_/
                  |   |
  version-negotiator  |
              version-argument

Ein Versionsbezeichner ist ein String, der genügend Informationen enthält, um eine bestimmte Revision zu laden. Die „Version Negotiator“-Komponente gibt den Aushandlungsmechanismus zum Laden einer Revision an. Derzeit kann dies entweder id oder rel sein. Der id-Negotiator nimmt als Versionsargument die gewünschte Revisions-ID entgegen. Der rel-Negotiator nimmt als Versionsargument entweder den String latest-version oder working-copy entgegen.

In Zukunft können weitere Negotiators entwickelt werden, zum Beispiel basierend auf Zeitstempel oder Workspaces.

Um zu veranschaulichen, wie eine bestimmte Entitätsrevision angefordert wird, stellen wir uns einen Node vor, der eine „Veröffentlichte“-Revision und eine nachfolgende „Entwurf“-Revision besitzt.

Mit JSON:API könnte man den „veröffentlichten“ Node anfordern, indem man /jsonapi/node/page/{{uuid}}?resourceVersion=rel:latest-version aufruft.

Um eine Entität, die sich noch im Arbeitsprozess befindet (also die „Entwurf“-Revision), anzuzeigen, kann man /jsonapi/node/page/{{uuid}}?resourceVersion=rel:working-copy aufrufen.

Um eine spezifische Revisions-ID anzufordern, kann man /jsonapi/node/page/{{uuid}}?resourceVersion=id:{{revision_id}} verwenden.

Es ist derzeit noch nicht möglich, eine Sammlung von Revisionen anzufordern. Dies ist in Entwicklung: #3009588: Provide a collection resource where a version history can be obtained (`version-history`, `predecessor-version` and `successor-version` link relations).

Artikel von Drupal Documentation.