Osnovni koncepti
JSON:API ima mnogo koncepata u svojoj specifikaciji, ali nisu svi ovde dokumentovani. Međutim, korisnici modula ne moraju u potpunosti da razumeju sve koncepte specifikacije da bi bili produktivni sa ovim modulom. Ako ipak želite da dublje istražite kako su JSON:API dokumenti strukturirani, zašto modul nešto radi na jedan ili drugi način, ili jednostavno želite da naučite više o dizajnu modula, preporučuje se čitanje specifikacije na jsonapi.org.
Struktura dokumenta
JSON:API je veoma strog po pitanju kako JSON dokumenti treba da budu strukturirani i koje informacije moraju biti prisutne u svakom zahtevu i/ili odgovoru.
Svako telo zahteva/odgovora mora biti unutar jednog JSON objekta.
{
// vaši podaci ovde...
}
Podaci, ili informacije specifične za resurs ili resurse, moraju se nalaziti unutar ovog glavnog objekta pod ključem data. „Member” je jednostavno unapred definisani ključ u JSON objektu. data član može biti ili objekat ({}) ili niz ([]). Prilikom kreiranja ili ažuriranja resursa, to će uvek biti jedan objekat ({}) koji predstavlja jednu stavku. Samo prilikom dobijanja „kolekcije” više resursa, ova osobina će biti niz.
{
"data": {
// Vaši podaci o resursu idu ovde.
}
}
Ostali članovi na najvišem nivou uključuju: errors, meta, links i included. Od ovih, included će se najčešće koristiti, ali će biti obrađen kasnije u dokumentaciji.
Za više informacija o strukturi na najvišem nivou, možete pogledati specifikaciju.
Unutar data i included članova nalaze se „resource objects” ili „resource identifier objects”. „Resource objects” predstavljaju sadržaj resursa (entiteta) sa kojima radite. „Resource identifier objects” su poput stranih ključeva u bazi podataka; oni identifikuju resurs bez prikazivanja njegovih polja. U Drupal terminima, „resource object” je uglavnom JSON prikaz jednog entiteta, kao što su jedan čvor, jedan termin taksonomije ili jedan korisnik. Opet u Drupal terminima, „resource identifier” je samo dovoljno informacija za učitavanje entiteta — imate njegov tip i ID i ništa više.
Svaki „resource object” mora sadržati dva člana: type i id. Jedini izuzetak je pri kreiranju novog entiteta, tada se id može izostaviti kako bi Drupal generisao ID za novi resurs. Ipak, moguće je da klijentska aplikacija pošalje UUID za resurs prilikom kreiranja novog entiteta. Svi ID-jevi u JSON:API-ju su UUID-jevi.
type član je uvek obavezan. Vrednost za type se dobija od imena tipa entiteta i bundle-a, gde je primenljivo. Tip za entitetski resurs uvek prati obrazac entity_type--bundle. Na primer, osnovni tipovi čvorova „article” i „basic page” biće predstavljeni kao: node--article i node--page.
Stoga, na entitetu bez obaveznih osobina ili polja, možete kreirati novi entitet sa sledećim JSON-om:
{
"data": {
"type": "node--my-bundle",
}
}
Ovo ipak ne bi bilo mnogo korisno. Moramo uključiti stvarne vrednosti za entitet. Da bismo to uradili, JSON:API ima dva člana za čuvanje vrednosti, attributes i relationships. attributes čuvaju vrednosti specifične za sam resurs, dok relationships predstavljaju vrednosti koje pripadaju drugom resursu u sistemu. U Drupal terminima, relationships najčešće predstavljaju vrednosti koje se čuvaju kao entity reference. Na primer, u osnovnom „article” bundle-u, to je uid svojstvo — jer je uid referenca na korisnika koji je autor članka. Telo dokumenta sa attributes i relationships može izgledati ovako:
{
"data": {
"type": "node--my-bundle",
"id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
"attributes": {
"title": "An Example"
},
"relationships": {
"uid": {
"data": {
"type": "user--user",
"id": "53bb14cc-544a-4cf2-88e8-e9cdd0b6948f"
}
}
}
}
}
Kao što vidite, uid se nalazi pod relationships članom. Kao i glavni resurs, sadrži type i id član jer je to poseban i različit resurs.
Napomena: uid nema nikakve attributes ni relationships. To je zato što JSON:API neće uključiti sadržaj odnosa osim ako to eksplicitno ne zatražite specijalnim query parametrom include. Više o tome kasnije u dokumentaciji (pogledajte „Dohvatanje resursa (GET)“).
Za više detalja o strukturi resource objekata pogledajte specifikaciju.
§ „Virtualni” identifikatori resursa
U nekim slučajevima, Drupal dozvoljava da odnos (entity reference) cilja resurs koji nije sačuvan u bazi i zato nije dohvatljiv kroz JSON:API. „Virtualni” identifikator resursa može signalizirati različite okolnosti u zavisnosti od konteksta, ali uvek odgovara resursu koji ne može biti pronađen.
Upotreba i značenje „virtualnog” identifikatora resursa u Drupal Core-u
Polje taksonomskog termina parent je najznačajniji primer ovog posebnog slučaja u Drupal core-u. Ovo polje odnosa može sadržati identifikator resursa za „virtualni” taksonomski termin. U tom slučaju, „virtualni” identifikator predstavlja <root> taksonomski termin. To znači da referencirani termin stoji na vrhu hijerarhije u svom vokabularu.
Pogledajte sledeći dokument odgovora za hipotetički taksonomski termin:
{
"data": {
"type": "taxonomy_term--tags",
"id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
"attributes": {
"name": "Politics"
},
"relationships": {
"parent": {
"data": [
{
"id": "virtual",
"type": "taxonomy_term--tags",
"meta": {
"links": {
"help": {
"href": "https://www.drupal.org/docs/8/modules/json-api/core-concepts#virtual",
"meta": {
"about": "Upotreba i značenje 'virtualnog' identifikatora resursa."
}
}
}
}
}
]
}
}
}
}
Primetite kako parent odnos ovog Term-a (polje entity reference) ima identifikator resursa gde id nije UUID, već "virtual". Ovo je neophodno jer vršni ili root Term ima referencu na nesačuvani <root> termin (target_id = 0) kao svog roditelja.
Zašto?
Pošto root termin nije sačuvan i pošto Term može imati više od jednog roditelja, ključno pitanje je: kako razlikovati Term koji:
- ima samo
Term3kao roditelja ([3])? - ima i ovaj nesačuvani root
Termkao roditelja iTerm3([0, 3])?
Odgovor je da, ako bi JSON:API izostavio nesačuvani root termin 0 umesto da koristi "virtual" ID, ne bi bilo moguće razlikovati ta dva slučaja!
§ „Nedostajući” identifikatori resursa
Drupal ne „čisti” odnose ka resursima koji su obrisani (entity reference polja koja referenciraju entitete koji su obrisani). Drugim rečima: Drupal ostavlja „viseće” odnose (entity references) na mestu.
Kada JSON:API naiđe na takve odnose, koristi „missing” (nedostajući) identifikator resursa.
Upotreba i značenje „missing” identifikatora resursa u Drupal Core-u
Ostajući na primeru za 'virtualni' identifikator: polje parent kod taksonomskog termina. Zamislite da je određeni taksonomski termin ranije imao termin „Belgium” kao roditelja, ali sada taj resurs više ne postoji — možda zato što je mala država Belgija prestala da postoji. Onda bi ovo polje sadržalo identifikator resursa za „missing” taksonomski termin.
Pogledajte sledeći dokument odgovora za hipotetički taksonomski termin:
{
"data": {
"type": "taxonomy_term--tags",
"id": "2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e",
"attributes": {
"name": "Politics"
},
"relationships": {
"parent": {
"data": [
{
"id": "missing",
"type": "unknown",
"meta": {
"links": {
"help": {
"href": "https://www.drupal.org/docs/8/modules/json-api/core-concepts#missing",
"meta": {
"about": "Upotreba i značenje 'missing' identifikatora resursa."
}
}
}
}
}
]
}
}
}
}
Primetite kako odnos parent ovog Term-a (entity reference polje) ima identifikator resursa gde id nije UUID, već "missing". Osim toga, njegov type je unknown (jer Drupal ne čuva bundle referenciranog entiteta, samo tip entiteta, pa određivanje JSON:API resource type imena nije moguće).
Članak sa Drupal Dokumentacije.