Backend JSON:API

JsonDrop API utilizza l’implementazione JSON:API per l’interazione backend/frontend ed è pienamente conforme alla:

Specifica JSON:API

Collezione Postman con endpoint pronti all’uso:

https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link

Con le sue stesse parole, la specifica JSON:API è:

[Una] specifica su come un client dovrebbe richiedere che le risorse vengano recuperate o modificate, e su come un server dovrebbe rispondere a tali richieste.

JSON:API è progettata per ridurre al minimo sia il numero di richieste sia la quantità di dati trasmessi tra client e server. Questa efficienza è ottenuta senza compromettere leggibilità, flessibilità o reperibilità.

Le strutture dati di Drupal, cioè tipi di entità, bundle e campi, si adattano perfettamente a JSON:API.

Abilitando il modulo JSON:API, ottieni immediatamente una REST API completa per ogni tipo presente nella tua applicazione Drupal. JSON:API analizza i tuoi tipi di entità e bundle in modo da fornire dinamicamente URL attraverso cui accedere a ciascuno di essi usando i metodi HTTP standard: GET, POST, PATCH e DELETE.

JSON:API adotta la filosofia che il modulo debba essere pronto per la produzione “out of the box”. Ciò significa che il modulo ha un’opinione precisa su dove risiederanno le tue risorse, quali metodi saranno immediatamente disponibili e lascia il controllo degli accessi al sistema di permessi di Drupal Core. Al momento, non ci sono pagine di configurazione disponibili. Questo significa che puoi avviare un’applicazione Drupal guidata dalle API con il minimo sforzo.

Le pagine figlie di questa documentazione includeranno:

• Concetti fondamentali della specifica JSON:API – e come si applicano a Drupal
• Una panoramica generale dell’API resa disponibile dal modulo
• Informazioni pratiche su come costruire le tue richieste HTTP
• Come autenticare le tue richieste
• “Gotchas” comuni
• Documentazione specifica per:
  • Recupero di singole risorse (GET)
  • Recupero di collezioni di risorse (GET con filtri, paginazione e ordinamento)
  • Creazione di nuove risorse (POST)
  • Aggiornamento di risorse esistenti (PATCH)
  • Eliminazione di risorse esistenti (DELETE)

Se hai domande specifiche, crea una richiesta di supporto nella coda delle issue del modulo JSON:API [480 issues].

L’API resa disponibile dal modulo JSON:API è incentrata sui tipi di entità e bundle di Drupal. Ogni bundle riceve il proprio URL univoco, che segue uno schema comune.

A differenza del modulo REST Core di Drupal, questi percorsi non sono configurabili e sono tutti abilitati di default. A differenza del REST core, JSON:API non è semplicemente un formato come JSON o HAL+JSON. Comprende un insieme molto più ampio di regole su come funzionerà la tua API. Stabilisce quali metodi HTTP devono essere utilizzati, quali codici di risposta HTTP devono essere restituiti in circostanze specifiche, il formato del corpo della risposta e il collegamento tra risorse. Per un confronto più dettagliato, vedi JSON:API vs. il modulo REST di core.

Tipi

Ogni risorsa in JSON:API deve avere una proprietà type globalmente univoca. L’implementazione JSON:API di Drupal deriva questa proprietà dal nome macchina del tipo di entità e dal nome macchina del bundle. Ad esempio, articoli, pagine e utenti ricevono rispettivamente i tipi node--article, node--pages e user--user. Nota che il tipo di entità utente in Drupal non ha un bundle. Quando un tipo di entità non ha un bundle, il tipo di entità viene semplicemente ripetuto per coerenza.

Struttura degli URL

Un URL JSON:API ha questo aspetto:

GET|POST     /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

Ogni tipo di risorsa deve essere univocamente raggiungibile nell’API. Ciò significa che ogni tipo disponibile per l’API deve avere un URL univoco. Oltre a richiedere che ogni tipo sia raggiungibile, questo implica sempre che un solo tipo di risorsa possa essere recuperato da un determinato URL. L’implementazione Drupal segue lo schema: /jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}].

L’URL è sempre prefissato da /jsonapi.

Dopo di ciò, l’ID del tipo di entità e l’ID del bundle sono concatenati da uno slash. Nota che non esiste alcun URL a /jsonapi/node, questo perché quell’URL violerebbe la specifica servendo più tipi di risorse (a causa dei molteplici bundle) da un singolo URL.

Esistono:
/jsonapi/node/page
/jsonapi/node/article

Non esiste:
/jsonapi/node

Dopo il tipo di entità e l’ID del bundle, c’è una parte opzionale relativa all’ID. Per indirizzare una singola risorsa, sia per recuperarla, aggiornarla o eliminarla, devi includere questa parte nel percorso. È sempre l’UUID della risorsa. Quando si crea una nuova risorsa, con o senza ID, o si recupera una collezione di risorse di un singolo tipo, questa parte del percorso viene omessa.

GET, POST
/jsonapi/node/article

PATCH, DELETE
/jsonapi/node/article/{uuid}

Metodi HTTP

JSON:API specifica quali metodi HTTP accettare. Questi sono: GET, POST, PATCH e DELETE. In particolare, PUT non è incluso.

• GET - Recupera dati, può essere una collezione di risorse o una singola risorsa
• POST - Crea una nuova risorsa
• PATCH - Aggiorna una risorsa esistente
• DELETE - Elimina una risorsa esistente

Header delle Richieste

Assicurati di usare gli header 'Content type' e 'Accept' quando appropriato. Vedi Responsabilità del client per maggiori dettagli.

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Codici di Risposta

La specifica JSON:API definisce anche le risposte accettabili. L’implementazione Drupal utilizza un sottoinsieme di queste. Il modulo può rispondere con i seguenti codici:

• 200 OK - Tutte le richieste GET e PATCH riuscite
• 201 Created - Tutte le richieste POST riuscite (la risposta include la nuova risorsa creata)
• 204 No Content - Tutte le richieste DELETE riuscite

Articolo da Documentazione Drupal.