Révisions

Le module JSON:API expose les révisions d’entité en tant que versions de ressource, dans une approche inspirée par le RFC5829 : Types de relations de liens pour une navigation simple entre versions de ressources web.

Limitations actuelles :

• Les versions de ressource (révisions d’entité) ne peuvent être que lues. Et seuls les types d’entité Node et Media (node--* et media--*) peuvent être exposés via JSON:API (en raison de l’absence d’une API formelle de contrôle d’accès aux révisions dans le noyau Drupal ; une fois disponible, tous les types d’entités révisables seront accessibles via JSON:API, voir #3031271 : Support de la négociation de version pour tout type d’entité (actuellement seuls Node & Media sont supportés)).
• Cependant, les versions de ressource sont créées automatiquement lors d’un PATCH sur une ressource d’un type configuré pour créer automatiquement des nouvelles versions (révisions). Nous travaillons à permettre qu’une requête PATCH sur une ressource versionnable spécifie si une nouvelle révision doit être créée ou non, via #2993557 : Autoriser la création optionnelle de nouvelle révision lors du PATCH d’entités révisables pour supporter la fonction d’auto-enregistrement via JSON:API..

Le support des révisions n’est pas une partie officielle de la spécification JSON:API. Cependant, plusieurs "profils" sont en cours de développement (pas encore officiels dans la spécification, mais déjà intégrés dans JSON:API v1.1) pour standardiser certains comportements personnalisés du module JSON:API (tous conformes à la spécification).

Ainsi, le module JSON:API vise une compatibilité maximale avec d’autres systèmes et minimise les « drupalisms » que le développeur utilisant JSON:API devra connaître.

Une "version" dans le module JSON:API correspond à toute révision qui a déjà été ou est actuellement la révision par défaut. Toutes les révisions ne sont pas considérées comme une "version". Les révisions non marquées comme "défaut" sont considérées comme des "copies de travail" car elles ne sont généralement pas publiques et sont les révisions sur lesquelles la plupart des modifications sont appliquées.

Quand le module Content Moderation est installé, il est possible que la révision par défaut la plus récente ne soit *pas* la dernière révision.

La requête d’une version de ressource se fait via un paramètre d’URL. Elle a la forme suivante :

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

Un identifiant de version est une chaîne contenant suffisamment d’informations pour charger une révision particulière. Le composant de négociation nomme le mécanisme pour charger une révision. Actuellement, cela peut être id ou rel. Le négociateur id prend un argument version qui est l’ID de la révision désirée. Le négociateur rel prend un argument version qui est soit la chaîne latest-version soit la chaîne working-copy.

À l’avenir, d’autres négociateurs pourront être développés, par exemple basés sur un horodatage ou un espace de travail.

Pour illustrer comment une révision d’entité particulière est demandée, imaginons un node avec une révision "Publiée" et une révision "Brouillon" suivante.

Avec JSON:API, on peut demander le node "Publié" via /jsonapi/node/page/{{uuid}}?resourceVersion=rel:latest-version.

Pour prévisualiser une entité en cours de modification (la révision "Brouillon"), on peut demander /jsonapi/node/page/{{uuid}}?resourceVersion=rel:working-copy.

Pour demander une révision spécifique par ID, on peut utiliser /jsonapi/node/page/{{uuid}}?resourceVersion=id:{{revision_id}}.

Il n’est pas encore possible de demander une collection de révisions. Cette fonctionnalité est en cours de développement dans l’issue #3009588 : Fournir une ressource collection pour obtenir l’historique des versions (liens version-history, predecessor-version et successor-version).

Article extrait de la documentation Drupal.