Scroll
JSON:API vs. de REST-module van Drupal core
TL;DR
Kies REST als je niet-entiteitsgegevens wilt exposen. In alle andere gevallen kies je JSON:API.
Iets genuanceerder:
- De REST-module van core staat alles toe (elk formaat, elke logica, elke HTTP-methode) en is extreem configureerbaar. Krachtig maar complex en daardoor relatief breekbaar.
- JSON:API richt zich op het coherent exposen van Drupal’s grootste kracht (entiteiten/datamodellering). Eenvoudig maar voor de meeste use-cases krachtig genoeg.
Feature matrix
| Kenmerk | JSON:API | REST | Opmerking |
|---|---|---|---|
| Entiteiten als resources geëxposeerd | ✔️ | ✔️ | REST: per entiteitstype configureren. JSON:API: alles standaard geëxposeerd. Beide: respecteren Entity Access. |
| Aangepaste gegevens als resources exposen | ✔️ | Schrijf custom @RestResource-plugins. JSON:API ondersteunt alleen entiteiten. | |
| Individuele resources ophalen | ✔️ | ✔️ | |
| Lijsten met resources ophalen | ✔️ | soort van |
REST: je moet een View configureren en een “REST export”-weergave instellen. |
| Pagineren van resource-lijsten | ✔️ | Extra modules zoals de Pager Serializer zijn nodig. | REST: niet ondersteund! REST export-views geven alle resources terug. |
| Filteren van resource-lijsten | ✔️ | soort van |
REST: alleen als je een exposed filter maakt voor elk veld en elke mogelijke operator |
| Sorteren van resources | ✔️ | ||
| Includes/insluiten | ✔️ | Alleen in HAL+JSON | |
| Geen onnodige wrapping van veldwaarden | ✔️ | Zowel de HAL-normalisatie als de standaardnormalisatie (en dus alle formaten) exposen precies de in-memory PHP-datastructuren die Drupal gebruikt, wat pijnlijke DX oplevert voor consumers. JSON:API vereenvoudigt de normalisatie van velden met enkele kardinaliteit en enkele eigenschap. | |
| Mogelijkheid om velden weg te laten die de consumer niet nodig heeft | ✔️ | ||
| Consistente URL’s | ✔️ | ||
| Consumer kan beschikbare resourcetypen ontdekken | ✔️ | ||
| Drupal-agnostische responsstructuur | ✔️ | REST: de HAL-normalisatie is in theorie vrij van Drupalisms, maar in de praktijk niet. | |
| Clientbibliotheken | ✔️ | ||
| Uitbreidbare specificatie | WIP | ||
| Geen configuratie nodig | ✔️ | REST: elke @RestResource-plugindefinitie kan worden geëxposeerd, maar moet worden geconfigureerd om te worden geëxposeerd. Per stuk moet je toegestane formaten, toegestane authenticatieproviders en desgewenst zelfs toegestane HTTP-methoden kiezen. JSON:API: alle entiteiten worden automatisch geëxposeerd, entity/field access wordt gerespecteerd, alle geïnstalleerde authenticatieproviders zijn automatisch toegestaan. |
Meer informatie
Bekijk de motivatie om de JSON:API-module aan Drupal core toe te voegen, en de toelichting op de module-architectuur.
Artikel uit Drupal-documentatie.