Revisiones

El módulo JSON:API expone las revisiones de entidades como versiones de recursos, de una manera inspirada en la RFC5829: Tipos de relaciones de enlace para navegación de versiones simples entre recursos web.

Limitaciones actuales:

• Las versiones de recursos (revisiones de entidades) solo pueden ser leídas. Y solo para los tipos de entidad Node y Media (node--* y media--*), JSON:API puede hacer accesibles las versiones de recursos (debido a la ausencia de una API formal de control de acceso a revisiones en el núcleo de Drupal. Una vez que esté disponible, se habilitará para todos los tipos de entidades revisables mediante JSON:API. Ver #3031271: Soporte para la negociación de versiones para cualquier tipo de entidad (actualmente solo Node & Media son soportados)).
• Sin embargo, las versiones de recursos se crean automáticamente al hacer PATCH a un recurso de un tipo de recurso (tipo de entidad + bundle) que está configurado para crear nuevas versiones (revisiones) automáticamente. Se está trabajando para permitir que una solicitud PATCH a un recurso versionable especifique si debe crearse o no una nueva revisión, en #2993557: Permitir la creación opcional de nuevas revisiones al hacer PATCH sobre entidades revisables para soportar la funcionalidad de autoguardado vía JSON:API.

El soporte de revisiones no es parte oficial de la especificación JSON:API. Sin embargo, se están desarrollando varios “perfiles” (tampoco son parte oficial aún de la especificación, pero ya están comprometidos en JSON:API v1.1) para estandarizar cualquier comportamiento personalizado que el módulo JSON:API haya desarrollado (todos aún cumplen la especificación).

De este modo, el módulo JSON:API debería ser lo más compatible posible con otros sistemas y minimizar los “drupalismos” que un desarrollador necesitaría conocer al trabajar con una implementación de JSON:API.

Una “versión” en el módulo JSON:API es cualquier revisión que haya sido o sea una revisión predeterminada. No todas las revisiones se consideran una “versión”. Las revisiones que no están marcadas como “revisión predeterminada” se consideran “copias de trabajo”, ya que normalmente no están disponibles públicamente y son las revisiones sobre las que se aplica la mayoría del trabajo nuevo.

Cuando el módulo Content Moderation está instalado, es posible que la revisión predeterminada más reciente no sea la última revisión.

Solicitar una versión de recurso se hace mediante un parámetro de consulta en la URL. Tiene la siguiente forma:

            identificador-de-versión
                  __|__
                 /     \
?resourceVersion=foo:bar
                 \_/ \_/
                  |   |
  negociador-de-versión  |
               argumento-de-versión

Un identificador de versión es una cadena con la información suficiente para cargar una revisión en particular. El componente negociador de versión nombra el mecanismo de negociación para cargar una revisión. Actualmente, puede ser id o rel. El negociador id recibe como argumento de versión el ID de revisión deseado. El negociador rel recibe como argumento de versión la cadena latest-version o la cadena working-copy.

En el futuro podrían desarrollarse otros negociadores, por ejemplo, uno basado en timestamp o en workspaces.

Para ilustrar cómo se solicita una revisión específica de una entidad, imagina un nodo que tiene una revisión “Publicada” y una revisión posterior en estado “Borrador”.

Usando JSON:API, se podría solicitar el nodo “Publicado” usando: /jsonapi/node/page/{{uuid}}?resourceVersion=rel:latest-version.

Para previsualizar una entidad que aún está en proceso (es decir, la revisión “Borrador”), se podría solicitar: /jsonapi/node/page/{{uuid}}?resourceVersion=rel:working-copy.

Para solicitar un ID de revisión específico, se puede usar: /jsonapi/node/page/{{uuid}}?resourceVersion=id:{{revision_id}}.

Aún no es posible solicitar una colección de revisiones. Esto está en desarrollo en la issue #3009588: Proporcionar un recurso de colección donde se pueda obtener el historial de versiones (version-history, predecessor-version y successor-version link relations).

Artículo de la Documentación de Drupal.