Revisies
De JSON:API-module stelt entiteitsrevisies bloot als resourceversies, op een manier geïnspireerd door RFC5829: Link Relation Types for Simple Version Navigation between Web Resources.
Huidige beperkingen:
- Resourceversies (entiteitsrevisies) kunnen alleen worden gelezen. En alleen voor
Node- enMedia-entiteitstypes (node--*- enmedia--*-resourcetypes) kan JSON:API de resourceversies toegankelijk maken (door het ontbreken van een formele entiteitsrevisie-toegangscontrole-API in Drupal core. Zodra die beschikbaar is, zullen we alle revisieerbare entiteitstypes beschikbaar maken via JSON:API, zie #3031271: Ondersteun versie-onderhandeling voor elk entiteitstype (momenteel alleen Node & Media ondersteund)). - Resourceversies worden echter automatisch aangemaakt wanneer je een resource van een resourcetype (entiteitstype + bundle)
PATCH-t die is geconfigureerd om automatisch nieuwe versies (revisies) te maken. We werken eraan om het mogelijk te maken dat eenPATCH-verzoek naar een versieerbare resource kan aangeven of er een nieuwe revisie moet worden aangemaakt of niet, zie #2993557: Optioneel aanmaken van nieuwe revisie toestaan bij PATCHen van revisieerbare entiteiten om autosave-functionaliteit via JSON:API te ondersteunen.
Revisie-ondersteuning is geen officieel onderdeel van de JSON:API-specificatie. Er worden echter een aantal "profielen" ontwikkeld (ook geen officieel onderdeel van de spec, maar al wel opgenomen in JSON:API v1.1) om eventuele aangepaste gedragingen die de JSON:API-module heeft ontwikkeld te standaardiseren (die allemaal nog steeds specificatie-conform zijn).
Op deze manier moet de JSON:API-module maximaal compatibel zijn met andere systemen en het aantal "Drupalisms" minimaliseren dat een ontwikkelaar die met een JSON:API-implementatie werkt, moet kennen.
Een "versie" in de JSON:API-module is elke revisie die eerder of momenteel een standaardrevisie was. Niet alle revisies worden beschouwd als een "versie". Revisies die niet als "standaard"-revisie zijn gemarkeerd, worden beschouwd als "werkversies" omdat ze meestal niet publiekelijk beschikbaar zijn en het de revisies zijn waarop het meeste nieuwe werk wordt toegepast.
Wanneer de Content Moderation-module is geïnstalleerd, is het mogelijk dat de meest recente standaardrevisie *niet* de laatste revisie is.
Het aanvragen van een resourceversie gebeurt via een URL-queryparameter. Deze heeft de volgende vorm:
versie-identificator
__|__
/ \
?resourceVersion=foo:bar
\_/ \_/
| |
versie-onderhandelaar |
versie-argument
Een versie-identificator is een string met voldoende informatie om een bepaalde revisie te laden. De versie-onderhandelingscomponent benoemt het onderhandelingsmechanisme voor het laden van een revisie. Momenteel kan dit ofwel id of rel zijn. De id-onderhandelaar neemt een versie-argument dat de gewenste revisie-ID is. De rel-onderhandelaar neemt een versie-argument dat ofwel de string latest-version of de string working-copy is.
In de toekomst kunnen andere onderhandelaars worden ontwikkeld. Bijvoorbeeld een onderhandelaar die gebaseerd is op tijdstempel of workspace.
Om te illustreren hoe een bepaalde entiteitsrevisie wordt opgevraagd, stel je een node voor die een "Gepubliceerde"-revisie heeft en een daaropvolgende "Concept"-revisie.
Met JSON:API kun je de "Gepubliceerde" node opvragen door te verzoeken: /jsonapi/node/page/{{uuid}}?resourceVersion=rel:latest-version.
Om een entiteit te bekijken die nog in bewerking is (d.w.z. de "Concept"-revisie), kun je verzoeken: /jsonapi/node/page/{{uuid}}?resourceVersion=rel:working-copy.
Om een specifieke revisie-ID op te vragen, kun je verzoeken: /jsonapi/node/page/{{uuid}}?resourceVersion=id:{{revision_id}}.
Het is nog niet mogelijk om een verzameling van revisies op te vragen. Dit is nog in ontwikkeling in issue #3009588: Voorzie een collectie-resource waar een versiegeschiedenis kan worden verkregen (`version-history`, `predecessor-version` en `successor-version` link-relaties).
Artikel van Drupal Documentatie.