JSON:API-backend

JsonDrop API gebruikt de JSON:API-implementatie voor backend/frontend-interactie en een volledig conforme implementatie van de:

JSON:API-specificatie

Postman-collectie met kant-en-klare endpoints:

https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link

In haar eigen woorden is de JSON:API-specificatie:

[Een] specificatie voor hoe een client moet verzoeken dat resources opgehaald of gewijzigd worden, en hoe een server op die verzoeken moet reageren.

JSON:API is ontworpen om zowel het aantal verzoeken als de hoeveelheid data die wordt overgedragen tussen clients en servers te minimaliseren. Deze efficiëntie wordt bereikt zonder in te boeten aan leesbaarheid, flexibiliteit of vindbaarheid.

De datastructuren van Drupal, d.w.z. entiteitstypes, bundels en velden, zijn bijzonder geschikt voor JSON:API.

Door de JSON:API-module in te schakelen, krijg je onmiddellijk een volledige REST API voor elk type in je Drupal-applicatie. JSON:API inspecteert je entiteitstypes en bundels zodat het dynamisch URL’s kan aanbieden waarmee je elk van hen kunt benaderen via de standaard HTTP-methodes: GET, POST, PATCH en DELETE.

JSON:API hanteert de filosofie dat de module “out of the box” productieklaar moet zijn. Dit betekent dat de module een sterke mening heeft over waar je resources zich bevinden, welke methodes direct beschikbaar zijn en laat toegangsbeheer over aan het permissiesysteem van Drupal Core. Op dit moment zijn er geen configuratiepagina’s beschikbaar. Dit betekent dat je snel en met minimale inspanning een API-gedreven Drupal-applicatie kunt opzetten.

De subpagina’s van deze documentatiepagina zullen bevatten:

• Kernconcepten van de JSON:API-specificatie – en hoe ze van toepassing zijn op Drupal
• Een breed overzicht van de API die de module beschikbaar maakt.
• Praktische informatie over het opstellen van je HTTP-verzoeken.
• Hoe je je verzoeken kunt authenticeren.
• Veelvoorkomende valkuilen.
• Specifieke documentatie voor:
  • Individuele resources ophalen (GET)
  • Collecties van resources ophalen (GET met filters, paginatie en sortering)
  • Nieuwe resources aanmaken (POST)
  • Bestaande resources bijwerken (PATCH)
  • Bestaande resources verwijderen (DELETE)

Als je specifieke vragen hebt, maak dan een supportaanvraag aan in de issue queue van de JSON:API-module [480 issues].

De API die de JSON:API-module beschikbaar maakt, is gecentreerd rond de entiteitstypes en bundels van Drupal. Elke bundel krijgt zijn eigen, unieke URL-pad, die allemaal een gedeeld patroon volgen.

In tegenstelling tot de Drupal Core REST-module zijn deze paden niet configureerbaar en allemaal standaard ingeschakeld. In tegenstelling tot core REST is JSON:API niet simpelweg een formaat zoals JSON of HAL+JSON. Het omvat een veel bredere set regels over hoe je API zal werken. Het bepaalt welke HTTP-methodes gebruikt moeten worden, welke HTTP-responscodes moeten worden teruggegeven onder specifieke omstandigheden, het formaat van je response body en de koppeling tussen resources. Voor een meer gedetailleerde vergelijking, zie JSON:API vs. core’s REST-module.

Types

Elke resource in JSON:API moet een wereldwijd unieke type-eigenschap hebben. De Drupal JSON:API-implementatie leidt deze type-eigenschap af van de machine name van het entiteitstype en de bundel. Bijvoorbeeld, artikelen, pagina’s en gebruikers krijgen respectievelijk de types node--article, node--pages, en user--user. Merk op dat het user-entiteitstype in Drupal geen bundel heeft. Wanneer een entiteitstype geen bundel heeft, wordt het entiteitstype simpelweg herhaald voor consistentie.

URL-structuur

Een JSON:API-URL ziet er zo uit:

GET|POST     /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

Elk resourcetype moet uniek aanspreekbaar zijn in de API. Dit betekent dat elk type dat beschikbaar is voor de API een unieke URL moet hebben. Dit houdt ook altijd in dat slechts één resourcetype opgehaald kan worden met een bepaalde URL. De Drupal-implementatie volgt het patroon: /jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}].

De URL is altijd voorafgegaan door /jsonapi.

Daarna worden het entiteitstype-ID en het bundel-ID gekoppeld door een slash. Merk op dat er geen URL is op /jsonapi/node, omdat deze URL de specificatie zou schenden door meerdere resourcetypes (vanwege meerdere bundeltypes) te serveren vanuit één enkele URL.

Bestaat wel:
/jsonapi/node/page
/jsonapi/node/article

Bestaat niet:
/jsonapi/node

Na het entiteitstype en bundel-ID is er een optioneel ID-gedeelte. Om één enkele resource aan te spreken, om deze op te halen, bij te werken of te verwijderen, moet je dit padgedeelte opnemen. Dit is altijd de UUID van de resource. Bij het aanmaken van een nieuwe resource, met of zonder ID, of het ophalen van een collectie van resources van één type, wordt het ID-padgedeelte weggelaten.

GET, POST
/jsonapi/node/article

PATCH, DELETE
/jsonapi/node/article/{uuid}

HTTP-methodes

JSON:API specificeert welke HTTP-methodes geaccepteerd moeten worden. Dat zijn: GET, POST, PATCH en DELETE. Opvallend is dat PUT niet is inbegrepen.

• GET - Data ophalen, kan een collectie van resources of een individuele resource zijn
• POST - Een nieuwe resource aanmaken
• PATCH - Een bestaande resource bijwerken
• DELETE - Een bestaande resource verwijderen

Request headers

Zorg ervoor dat je 'Content type'- en 'Accept'-headers gebruikt wanneer dat nodig is. Zie Client responsibility voor meer details.

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Response codes

De JSON:API-specificatie bepaalt ook de toegestane responses. De Drupal-implementatie gebruikt een subset hiervan. De module kan reageren met de volgende codes:

• 200 OK - Alle succesvolle GET- en PATCH-verzoeken
• 201 Created - Alle succesvolle POST-verzoeken (response bevat de nieuw aangemaakte resource)
• 204 No Content - Alle succesvolle DELETE-verzoeken

Artikel van Drupal Documentatie.