Revisioni

Il modulo JSON:API espone le revisioni delle entità come versioni delle risorse, in un modo ispirato all’RFC5829: Link Relation Types for Simple Version Navigation between Web Resources.

Limitazioni attuali:

• Le versioni delle risorse (revisioni delle entità) possono solo essere lette. E solo per i tipi di entità Node e Media (tipi di risorsa node--* e media--*) JSON:API può rendere accessibili le versioni delle risorse (a causa dell’assenza di una API formale di controllo degli accessi alle revisioni nel core di Drupal; una volta disponibile, renderemo tutti i tipi di entità revisionabili disponibili tramite JSON:API, vedi #3031271: Supportare la negoziazione delle versioni per qualsiasi tipo di entità (attualmente supportati solo Node e Media)).
• Tuttavia, le versioni delle risorse vengono create automaticamente quando si effettua un PATCH su una risorsa di un tipo (tipo di entità + bundle) configurato per creare automaticamente nuove versioni (revisioni). Stiamo lavorando per rendere possibile che una richiesta PATCH a una risorsa revisionabile specifichi se deve essere creata o meno una nuova revisione, vedi #2993557: Consentire la creazione opzionale di nuove revisioni quando si effettua PATCH su entità revisionabili per supportare la funzionalità di salvataggio automatico tramite JSON:API..

Il supporto alle revisioni non è parte ufficiale della specifica JSON:API. Tuttavia, sono in fase di sviluppo diversi "profili" (anch’essi non ufficialmente parte della specifica, ma già inseriti in JSON:API v1.1) per standardizzare qualsiasi comportamento personalizzato che il modulo JSON:API ha sviluppato (tutti comunque conformi alla specifica).

In questo modo, il modulo JSON:API dovrebbe essere il più compatibile possibile con altri sistemi e minimizzare i "Drupalisms" che uno sviluppatore che lavora con un’implementazione JSON:API deve conoscere.

Una "versione" nel modulo JSON:API è qualsiasi revisione che sia stata precedentemente, o sia attualmente, una revisione predefinita. Non tutte le revisioni sono considerate una "versione". Le revisioni non contrassegnate come "predefinite" sono considerate "bozze di lavoro" poiché di solito non sono pubblicamente disponibili e sono le revisioni su cui viene applicato la maggior parte del nuovo lavoro.

Quando il modulo Content Moderation è installato, è possibile che la revisione predefinita più recente non sia l’ultima revisione.

Richiedere una versione di risorsa si fa tramite un parametro di query nell’URL. Ha la seguente forma:

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

Un identificatore di versione è una stringa con informazioni sufficienti per caricare una particolare revisione. Il componente version-negotiator nomina il meccanismo di negoziazione per caricare una revisione. Attualmente può essere id o rel. Il negoziatore id richiede come argomento l’id della revisione desiderata. Il negoziatore rel richiede come argomento la stringa latest-version o la stringa working-copy.

In futuro, potrebbero essere sviluppati altri negoziatori. Per esempio, un negoziatore basato su timestamp o workspace.

Per illustrare come viene richiesta una particolare revisione di un’entità, immagina un nodo che ha una revisione "Pubblicata" e una successiva revisione "Bozza".

Usando JSON:API, si potrebbe richiedere il nodo "Pubblicato" richiedendo /jsonapi/node/page/{{uuid}}?resourceVersion=rel:latest-version.

Per visualizzare in anteprima un’entità ancora in lavorazione (cioè la revisione "Bozza") si potrebbe richiedere /jsonapi/node/page/{{uuid}}?resourceVersion=rel:working-copy.

Per richiedere uno specifico id di revisione, si può fare la richiesta /jsonapi/node/page/{{uuid}}?resourceVersion=id:{{revision_id}}.

Non è ancora possibile richiedere una collezione di revisioni. Questa funzionalità è ancora in fase di sviluppo nel ticket #3009588: Fornire una risorsa di collezione in cui è possibile ottenere una cronologia delle versioni (`version-history`, `predecessor-version` e `successor-version` link relations).

Articolo da Documentazione di Drupal.