Glossario dei termini

TL;DR:

• Le richieste HTTP vengono effettuate verso le risorse di JSON:API. Non confonderle con gli oggetti risorsa (resource objects).
• L’oggetto JSON che il client riceve si chiama documento.
• Un documento è sempre un oggetto JSON e ha i dati primari sotto la chiave data.
• I dati sotto quella chiave sono chiamati resource objects (oggetti risorsa) oppure resource identifier objects (oggetti identificatore di risorsa).
• Quando richiedi che i dati correlati siano incorporati nel documento, questo diventa un documento composto (compound document).
• Un documento composto è uno che ha una chiave included nell’oggetto di primo livello.
• Le risorse che restituiscono molti resource objects sono chiamate collection resources (risorse collezione).
• Le risorse che restituiscono un singolo resource object sono chiamate individual resources (risorse individuali).
• Le risorse che restituiscono informazioni sulle relazioni tra resource objects sono chiamate relationship resources (risorse relazione).
• In termini Drupal:
  • Resource Objects → Entità
  • Resource Identifier Objects → Elementi di campi di riferimento a entità
  • Document → Payload JSON della richiesta/risposta

Di seguito viene fornita una breve descrizione dei termini e dei concetti utilizzati quando si descrive il modulo JSON:API.

Questo glossario assomiglia molto alla specifica JSON:API, tuttavia cerca di inquadrare le definizioni per come si applicano a Drupal. Inoltre approfondisce alcune sottigliezze della specifica che potrebbero non essere ovvie a chi è alle prime armi e non ha familiarità con la specifica o con come leggere una specifica.

Molte di queste definizioni sono intrecciate tra loro. C’è un diagramma in fondo a questa pagina che colloca questi termini nel contesto in cui compaiono.

Risorsa

Un percorso dal quale è possibile recuperare un documento di risposta JSON:API. Una risorsa può essere trovata tramite il suo URL (uniform resource locator). Non va confusa con un “resource object”. Una risorsa non ha una corrispondenza uno-a-uno con i dati di un’applicazione.

In termini Drupal, questo significa che una risorsa JSON:API non è sinonimo di un’entità. Piuttosto, una risorsa è un luogo da cui si può recuperare i dati per un concetto. Ad esempio, quel concetto potrebbe essere “una raccolta di resource objects di tipo node--article” oppure “una rappresentazione del campo di riferimento a entità field_tags di uno specifico nodo articolo”.

Documento di risposta

Il corpo della risposta codificata in JSON restituito da una risorsa JSON:API. È la “busta” con cui i dati o gli errori vengono comunicati al client HTTP. Talvolta è chiamato oggetto di primo livello. Quando un documento ha un included come member del documento, è definito documento composto.

Documento composto

Un documento di risposta che contiene un included come member del documento. Un documento composto può essere usato per eliminare richieste HTTP incorporando i resource objects correlati accanto ai dati primari del documento di risposta. Un documento composto può essere richiesto aggiungendo un parametro di query include all’URL della richiesta.

Documento di errore

Un documento di risposta che contiene un errors come member del documento con uno o più oggetti errore. Non conterrà mai un member data. Il codice di stato HTTP di una risposta contenente un documento di errore sarà sempre un codice della classe 4xx o 5xx.

Risorsa individuale

Una risorsa che contiene un singolo resource object come member data del documento di risposta. Con autorizzazioni sufficienti, questa risorsa è leggibile e modificabile. In termini Drupal, questa risorsa può essere usata per “visualizzare”, “aggiornare” o “eliminare” una singola entità. Non può essere usata per “creare” un’entità.

Risorsa collezione

Una risorsa che contiene molti resource objects come member data del documento di risposta. Con autorizzazioni sufficienti, questa risorsa è leggibile e scrivibile. Queste risorse possono essere paginati, filtrati e ordinati. In termini Drupal, questa risorsa può essere usata per “creare” una nuova entità. Non può essere usata per “aggiornare” o “eliminare” entità nella collezione.

Risorsa relazione

Una risorsa che contiene un relationship object come oggetto di primo livello del documento di risposta. Contiene uno o più resource identifier objects che rappresentano ciascuno un riferimento da un resource object a un altro resource object. Con autorizzazioni sufficienti, questa risorsa è leggibile e modificabile. In termini Drupal, questa risorsa può essere usata per “visualizzare” o “modificare” gli elementi di un singolo campo di riferimento a entità.

Risorsa correlata

Una risorsa che è una risorsa collezione speciale contenente uno o più resource objects come member data del documento di risposta. I resource objects in questa collezione sono i soggetti di una relazione su un resource object referenziante. Questa risorsa è di sola lettura. In termini Drupal, questa risorsa può essere usata per “visualizzare” le entità che sono referenziate da un campo di riferimento a entità, ma non può essere usata per “aggiornare” tali entità o per “modificare” il campo di riferimento che le referenzia.

Member del documento

Un oggetto JSON che fa parte del documento JSON:API di primo livello. Questi oggetti si trovano sempre nel documento sotto chiavi definite dalla specifica (ad es. jsonapi, data, included o errors).

Resource Object

Una rappresentazione di un’entità come oggetto JSON. Non va confuso con una “risorsa”. Questo ha una corrispondenza uno-a-uno con i dati dell’applicazione.

Attributes Object

Un oggetto JSON che rappresenta informazioni riguardo al resource object in cui è definito. Gli attributi possono contenere qualsiasi valore JSON valido. In termini Drupal, questo oggetto rappresenta tutti i valori dei campi dell’entità che non sono riferimenti a entità.

Relationships Object (plurale)

Un oggetto JSON che contiene riferimenti dal resource object in cui è definito verso altri resource objects. Contiene molti member che sono relationship objects (singolare). In termini Drupal, questo oggetto rappresenta tutti i valori dei campi di riferimento a entità.

Relationship Object (singolare)

Un oggetto JSON che rappresenta i riferimenti dal resource object in cui è definito verso altri resource objects. Contiene resource identifier objects, ciascuno dei quali rappresenta una singola relazione verso un altro resource object. In termini Drupal, questo oggetto rappresenta un singolo campo di riferimento a entità.

Resource Identifier Object

Un oggetto JSON molto semplice che rappresenta una relazione da un resource object a un altro. Non va confuso con un “resource object”. Contiene soltanto le chiavi type e id e una chiave opzionale meta per contenere informazioni su quella relazione. In particolare, non contiene un member links.

Fornisce il “resource linkage” che, in un documento composto, consente al client HTTP di correlare i relationship objects con i resource object referenziati presenti nel member included di un documento composto.

Links Object

Un oggetto JSON che contiene collegamenti ipertestuali verso altre risorse.

Error Object

Un oggetto JSON che rappresenta un errore occorso durante l’elaborazione di una richiesta. Può rappresentare errori lato client, errori di validazione ed errori del server, tra le altre cose.

Articolo tratto dalla Documentazione di Drupal.