Inclusioni

TL;DR: Usa una query string come ?include=field_comments.uid per includere tutte le entità referenziate da field_comments e tutte le entità referenziate da uid su quelle entità!

JSON:API ti aiuta a eliminare richieste HTTP permettendoti di specificare i percorsi delle relazioni che desideri vengano incluse nel documento di risposta. Come?

Recuperare singole risorse

Recupera articolo

Immaginiamo di avere un articolo con due commenti e ciascuno di questi commenti ha lo stesso autore. Per ottenere tutti questi dati senza include, faresti prima una richiesta a GET /jsonapi/node/article/some-random-uuid:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  }
}

Recupera commento

Poi, faresti una richiesta a GET /node/article/some-random-uuid/field_comments:

{
  "data": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "two-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }
}

Recupera utenti

E ancora, avresti bisogno di fare due ulteriori richieste a /comment/one-random-uuid/uid e /comment/two-random-uuid/uid . Possiamo vedere che la seconda richiesta è del tutto inutile perché sappiamo che l’autore di entrambi i commenti è lo stesso nel nostro esempio.

Quindi, come possono aiutare gli include?

Recupera tutto in una volta usando include

È facile! Basta aggiungere un parametro di query all’URL della richiesta originale con i nomi dei campi di relazione che desideri includere, e il server cercherà tutto per te e lo aggiungerà al documento di risposta originale.

Nel nostro esempio, l’URL della richiesta che faresti sarebbe GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid. In altre parole, stai dicendo "per favore aggiungi gli oggetti risorsa per il campo field_comments sull’articolo, poi aggiungi anche gli oggetti risorsa per il campo uid sui commenti a cui si riferisce." Questi "percorsi di relazione" possono essere lunghi quanto vuoi, non ci sono limiti!

Il documento di risposta che riceveresti dal server sarebbe:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "data": [{
          "type": "comment",
          "id": "one-random-uuid",
        }, {
          "type": "comment",
          "id": "two-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  },
  "included": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "another-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "another-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "one-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Non è fantastico? Abbiamo ottenuto tutti i dati in una sola richiesta! Nota come l’oggetto risorsa utente sia incluso solo una volta, anche se è referenziato due volte. Questo mantiene bassa la dimensione della risposta. Nota anche come ora ci sia una chiave data in ciascun oggetto relazione. Questo ti permette di correlare gli oggetti risorsa inclusi con gli oggetti risorsa che li hanno referenziati.

Quando usare include?

Parlando di dimensione della risposta... in questo esempio, ci siamo risparmiati tempo ottenendo tutte le risorse in una singola richiesta. Tuttavia, in alcune circostanze, includere oggetti risorsa correlati renderà la risposta piuttosto grande e/o rallenterà il tempo di caricamento iniziale. In quel caso, potrebbe essere meglio fare più richieste in parallelo.

Include per collezioni e relazioni

Infine, il parametro di query include è supportato anche su collezioni e risorse di relazione! Gli include sulle collezioni possono farti risparmiare molte altre richieste.

Esempio di include per collezione

Recuperare include per una collezione potrebbe assomigliare a questo GET /jsonapi/node/article?include=uid. Gli included sono simili ma separati dai data (array invece di oggetto) come mostrato di seguito.

{
  "data": [{...}]
  "included": [{
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Articolo da Documentazione di Drupal.