Rečnik pojmova

TL;DR:

• HTTP zahtevi se šalju ka JSON:API resursima. Ne mešajte ih sa resource object (objekti resursa).
• JSON objekat koji klijent dobija naziva se dokument.
• Dokument je uvek JSON objekat i ima primarne podatke pod ključem data.
• Podaci pod tim ključem nazivaju se resource objects (objekti resursa) ili resource identifier objects (objekti identifikatora resursa).
• Kada tražite da povezani podaci budu ubačeni u dokument, on postaje kompozitni dokument (compound document).
• Kompozitni dokument ima ključ included u glavnom objektu.
• Resursi koji vraćaju više objekata resursa nazivaju se kolekcioni resursi (collection resources).
• Resursi koji vraćaju jedan objekat resursa nazivaju se pojedinačni resursi (individual resources).
• Resursi koji vraćaju informacije o odnosima između objekata resursa nazivaju se relationship resources.
• U Drupal terminima:
  • Resource Objects → Entiteti
  • Resource Identifier Objects → Stavke polja reference entiteta
  • Document → JSON telo zahteva/odgovora

Sledeće daje kratak opis termina i koncepata koji se koriste u opisu JSON:API modula.

Ovaj rečnik veoma liči na JSON:API specifikaciju, ali pokušava da definicije postavi iz ugla Drupala. Takođe proširuje suptilnosti specifikacije koje možda neće biti očigledne novim korisnicima koji nisu detaljno upoznati sa specifikacijom ili kako se čita specifikacija.

Mnoge od ovih definicija su međusobno povezane. Dijagram na dnu ove stranice prikazuje termine u kontekstu u kojem se pojavljuju.

Resurs

Lokacija na kojoj se može preuzeti JSON:API odgovorni dokument. Resurs se nalazi putem URL-a (universal resource locator). Ne treba ga mešati sa "resource object". Resurs nema jednoznačnu vezu sa podacima aplikacije.

U Drupal terminima, to znači da JSON:API resurs nije sinonim za entitet. Umesto toga, resurs je mesto gde možete preuzeti podatke za neki koncept. Na primer, taj koncept može biti „kolekcija resource objekata tipa node--article“ ili „reprezentacija polja reference entiteta field_tags za određeni node članka“.

Odgovorni dokument

JSON enkodirano telo odgovora vraćeno sa JSON:API resursa. To je „koverta” u kojoj se podaci ili greške šalju HTTP klijentu. Ponekad se naziva i glavni objekat. Kada dokument ima included člana dokumenta, naziva se kompozitni dokument.

Kompozitni dokument

Odgovorni dokument koji sadrži included člana dokumenta. Kompozitni dokument se koristi za eliminaciju HTTP zahteva tako što umeće povezane resource object-e zajedno sa primarnim podacima odgovora. Kompozitni dokument se može zatražiti dodavanjem include query parametra u URL zahteva.

Dokument o grešci (Error document)

Odgovorni dokument koji sadrži errors člana dokumenta sa jednim ili više objekata grešaka. Nikada neće sadržati data člana dokumenta. HTTP status kod odgovora koji sadrži dokument o grešci uvek će biti 4xx ili 5xx nivoa.

Pojedinačni resurs

Resurs koji sadrži jedan resource object kao data člana odgovornog dokumenta. Uz dovoljno prava, ovaj resurs je čitljiv i promenljiv. U Drupal terminima, ovaj resurs može da se koristi za 'pregled', 'ažuriranje' ili 'brisanje' pojedinačnog entiteta. Ne može se koristiti za 'kreiranje' entiteta.

Kolekcioni resurs

Resurs koji sadrži više resource object-a kao data člana odgovornog dokumenta. Uz dovoljno prava, ovaj resurs je čitljiv i zapisiv. Ovi resursi mogu biti paginirani, filtrirani i sortirani. U Drupal terminima, ovaj resurs može se koristiti za 'kreiranje' novog entiteta. Ne može se koristiti za 'ažuriranje' ili 'brisanje' entiteta u kolekciji.

Relationship resource

Resurs koji sadrži relationship object kao glavni objekat odgovornog dokumenta. Sadrži jedan ili više resource identifier object-a od kojih svaki predstavlja referencu sa jednog resource object-a ka drugom. Uz dovoljno prava, ovaj resurs je čitljiv i promenljiv. U Drupal terminima, koristi se za 'pregled' ili 'uređivanje' stavki polja reference entiteta.

Povezani resurs (Related Resource)

Resurs koji je poseban kolekcioni resurs i sadrži jedan ili više resource object-a kao data člana odgovornog dokumenta. Ovi resource objekti u kolekciji su subjekti odnosa u referenciranom resource objektu. Ovaj resurs je read-only. U Drupal terminima, koristi se za pregled entiteta na koje pokazuje polje reference entiteta, ali se ne može koristiti za ažuriranje tih entiteta ili za izmenu reference polja koje ih referencira.

Član dokumenta (Document member)

JSON objekat koji je deo glavnog JSON:API dokumenta. Ovi objekti su uvek locirani pod ključevima definisanim u specifikaciji (npr. jsonapi, data, included ili errors).

Resource Object

Reprezentacija entiteta kao JSON objekta. Ne treba ga mešati sa "resursom". Ovo ima jednoznačnu vezu sa podacima aplikacije.

Attributes Object

JSON objekat koji predstavlja informacije o resource objektu u kojem je definisan. Atributi mogu sadržati bilo koju validnu JSON vrednost. U Drupal terminima, ovaj objekat predstavlja sve vrednosti polja entiteta koje nisu reference na entitete.

Relationships Object (množina)

JSON objekat koji sadrži reference iz resource objekta u kojem je definisan, ka drugim resource objektima. Sadrži više članova koji su relationship objekti (u jednini). U Drupal terminima, ovaj objekat predstavlja sve vrednosti polja reference entiteta.

Relationship Object (jednina)

JSON objekat koji predstavlja reference iz resource objekta u kojem je definisan, ka drugim resource objektima. Sadrži resource identifier objects, od kojih svaki predstavlja pojedinačan odnos ka drugom resource objektu. U Drupal terminima, ovaj objekat predstavlja jedno polje reference entiteta.

Resource Identifier Object

Veoma jednostavan JSON objekat koji predstavlja odnos sa jednog resource objekta ka drugom. Ne treba ga mešati sa "resource object". Sadrži samo ključeve type i id i opciono meta za dodatne informacije o tom odnosu. Ne sadrži links član.

Omogućava „resource linkage” koji u