Woordenlijst van termen

TL;DR:

• HTTP-verzoeken worden gedaan naar JSON:API- resources. Verwar deze niet met resource objects.
• Het JSON-object dat de client ontvangt heet een document.
• Een document is altijd een JSON-object en heeft primaire data onder een data-sleutel.
• De data onder die sleutel heet resource objects of resource identifier objects.
• Wanneer je vraagt om gerelateerde data in het document in te bedden, wordt het een compound document.
• Een compound document is er één met een included-sleutel in het top-level object.
• Resources die veel resource objects teruggeven heten collection resources.
• Resources die één resource object teruggeven heten individual resources.
• Resources die informatie teruggeven over relaties tussen resource objects heten relationship resources.
• In Drupal-termen:
  • Resource Objects -> Entiteiten
  • Resource Identifier Objects -> Items van entiteitsreferentieveld
  • Document -> Request/response JSON-payload

Het volgende geeft een korte beschrijving van de termen en concepten die worden gebruikt bij het beschrijven van de JSON:API-module.

Deze woordenlijst lijkt sterk op de JSON:API-specificatie, maar probeert definities te kaderen zoals ze van toepassing zijn op Drupal. Ze gaat ook in op subtiliteiten van de specificatie die misschien niet meteen duidelijk zijn voor een nieuwkomer die niet zeer vertrouwd is met de specificatie of met hoe je een specificatie leest.

Veel van deze definities zijn met elkaar verweven. Onderaan staat een diagram dat deze termen toont in de context waarin ze voorkomen.

Resource

Een locatie waar een JSON:API- response-document kan worden opgehaald. Een resource is te vinden via zijn URL (uniform resource locator). Het moet niet worden verward met een “resource object”. Een resource heeft geen één-op-één-overeenkomst met de data van een applicatie.

In Drupal-termen betekent dit dat een JSON:API-resource niet synoniem is met een entiteit. In plaats daarvan is een resource een plaats waar je de data voor een concept kunt ophalen. Bijvoorbeeld, dat concept kan zijn “een collectie van resource objects van het type node--article” of “een representatie van het field_tags entiteitsreferentieveld van een specifieke article-node”.

Response Document

De JSON-gecodeerde response- body die terugkomt van een JSON:API- resource. Het is de “envelope” waarin data of fouten aan de HTTP-client worden gecommuniceerd. Dit wordt soms het top-level object genoemd. Wanneer een document een included- document member heeft, wordt het een compound document genoemd.

Compound Document

Een response-document dat een included- document member bevat. Een compound document kan HTTP-verzoeken verminderen door gerelateerde resource objects naast de primaire data van een response-document in te bedden. Je kunt een compound document opvragen door een include-queryparameter aan de URL van het verzoek toe te voegen.

Error Document

Een response-document dat een errors- document member bevat met één of meer error objects. Het zal nooit een data-document member bevatten. De HTTP-statuscode van een response met een error document zal altijd een 4xx- of 5xx-code zijn.

Individual Resource

Een resource die een enkel resource object bevat als het data- member van het response-document. Met voldoende autorisatie is deze resource leesbaar en wijzigbaar. In Drupal-termen kan deze resource worden gebruikt om een individuele entiteit te ‘viewen’, ‘updaten’ of ‘deleten’. Het kan niet worden gebruikt om een entiteit te ‘createn’.

Collection Resource

Een resource die veel resource objects bevat als het data- member van het response-document. Met voldoende autorisatie is deze resource leesbaar en schrijfbaar. Deze resources kunnen worden gepagineerd, gefilterd en gesorteerd. In Drupal-termen kan deze resource worden gebruikt om een nieuwe entiteit te ‘createn’. Het kan niet worden gebruikt om entiteiten in de collectie te ‘updaten’ of te ‘deleten’.

Relationship Resource

Een resource die een relationship object als top-level object van het response-document bevat. Het bevat één of meer resource identifier objects die elk een verwijzing vertegenwoordigen van een resource object naar een ander resource object. Met voldoende autorisatie is deze resource leesbaar en wijzigbaar. In Drupal-termen kan deze resource worden gebruikt om de items van één entiteitsreferentieveld te ‘viewen’ of te ‘editen’.

Related Resource

Een resource die een speciale collection resource is en één of meer resource objects bevat als het data- member van het response-document. De resource objects in deze collectie zijn de onderwerpen van een relatie op een verwijzend resource object. Deze resource is alleen-lezen. In Drupal-termen kan deze resource worden gebruikt om de entiteiten te ‘viewen’ die verwezen worden door een entiteitsreferentieveld, maar niet om die entiteiten te ‘updaten’ of het entiteitsreferentieveld dat naar hen verwijst te ‘editen’.

Document member

Een JSON-object dat deel uitmaakt van het top-level JSON:API- document. Deze objecten staan altijd in het document onder door de specificatie gedefinieerde sleutels (bijv. jsonapi, data, included of errors).

Resource Object

Een representatie van een entiteit als JSON-object. Verwar dit niet met een “resource”. Dit heeft een één-op-één-overeenkomst met de data van een applicatie.

Attributes Object

Een JSON-object dat informatie vertegenwoordigt over het resource object waarin het is gedefinieerd. Attributes mogen elke geldige JSON-waarde bevatten. In Drupal-termen vertegenwoordigt dit object alle entiteitsveldwaarden die geen entiteitsreferenties zijn.

Relationships Object (meervoud)

Een JSON-object dat verwijzingen bevat van het resource object waarin het is gedefinieerd naar andere resource objects. Het bevat meerdere members die relationship- (enkelvoud) objecten zijn. In Drupal-termen vertegenwoordigt dit object alle waarden van entiteitsreferentievelden.

Relationship Object (enkelvoud)

Een JSON-object dat de verwijzingen vertegenwoordigt van het resource object waarin het is gedefinieerd naar andere resource objects. Het bevat resource identifier objects, die elk één relatie naar een ander resource object vertegenwoordigen. In Drupal-termen vertegenwoordigt dit object één entiteitsreferentieveld.

Resource Identifier Object

Een heel eenvoudig JSON-object dat een relatie voorstelt van het ene resource object naar een ander. Verwar dit niet met een “resource object”. Het bevat alleen een type- en id-sleutel en optioneel een meta-sleutel om informatie over die relatie te bevatten. Opvallend: het bevat geen links-member.

Het levert “resource linkage”, wat in een compound document de HTTP-client in staat stelt om relationship objects te correleren met de verwezen resource object(en) in het included-member van een compound document.

Links Object

Een JSON-object dat hyperlinks bevat naar andere resources.

Error Object

Een JSON-object dat een fout vertegenwoordigt die optrad tijdens het verwerken van een verzoek. Dit kan clientfouten, validatiefouten en serverfouten vertegenwoordigen, onder andere.

Artikel uit de Drupal-documentatie.