Uključuje

TL;DR: Koristite query string kao što je ?include=field_comments.uid da uključite sve entitete na koje se referiše field_comments i sve entitete na koje se referiše uid na tim entitetima!

JSON:API vam pomaže da eliminišete HTTP zahteve tako što omogućava da navedete putanje odnosa (relationship paths) koje želite da budu uključene u odgovor. Kako?

Dohvatanje pojedinačnih resursa

Dohvati članak

Zamislite da imate članak sa dva komentara i oba komentara imaju istog autora. Da biste preuzeli sve ove podatke bez includes, prvo biste napravili zahtev na 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"
          }
        }
      }
    }
  }
}

Dohvati komentar

Zatim, napravili biste zahtev na 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"
          }
        }
      }
    }
  }
}

Dohvati korisnike

I opet, morali biste da napravite još dva zahteva na /comment/one-random-uuid/uid i /comment/two-random-uuid/uid . Možemo da vidimo da je drugi zahtev potpuno nepotreban jer znamo da su autori oba komentara isti u našem primeru.

Pa, kako uključivanja (includes) mogu da pomognu?

Dohvati sve odjednom pomoću include

Lako je! Samo dodavanjem query parametra u originalni URL zahteva sa imenima polja odnosa koje želite da uključite, server će znati da sve to potraži za vas i doda u originalni odgovor.

U našem primeru, URL zahtev koji biste napravili bi bio GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid. Drugim rečima, vi tražite: „molim te dodaj objekte resursa za polje field_comments na članku, zatim dodaj i objekte resursa za polje uid na komentarima na koje se to polje odnosi.“ Ove „putanje odnosa“ mogu biti dugačke koliko god želite, nema ograničenja!

Dokument odgovora koji biste dobili od servera izgledao bi ovako:

{
  "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"
    }
  }]
}

Zar nije sjajno? Sve podatke smo dobili jednim zahtevom! Primetite da je objekat resursa korisnika uključen samo jednom, iako se na njega referiše dva puta. Ovo održava veličinu odgovora malom. Takođe, primetite da sada postoji data ključ u svakom objektu odnosa. To vam omogućava da povežete uključene objekte resursa sa objektima koji su ih referencirali.

Kada koristiti include?

Kada govorimo o veličini odgovora... u ovom primeru smo sebi uštedeli vreme dobivši sve resurse jednim zahtevom. Ipak, u određenim situacijama uključivanje povezanih objekata resursa može učiniti veličinu odgovora veoma velikom i/ili usporiti vreme do prvog bajta. U tom slučaju, možda je i dalje bolje napraviti više paralelnih zahteva.

Include za kolekcije i odnose

Na kraju, query parametar include je podržan i na kolekcijama i odnosima! Includes za kolekcije mogu vam uštedeti mnoštvo dodatnih zahteva.

Primer include za kolekciju

Poziv sa includes za kolekciju može izgledati ovako GET /jsonapi/node/article?include=uid. included su slično odvojeni od data (niz umesto objekta), kao što je prikazano ispod.

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

Članak sa Drupal Dokumentacije.