Drupal als backend: GraphQL, JSON:API, RESTful en de dure fout die verborgen zit in de API-keuze

Een CTO vroeg me ooit, halverwege een planningsmeeting voor een decoupled Drupal-project: “Welke API moeten we dan gebruiken?”

Het werd even stil in de kamer. Frontend wilde GraphQL. Backend wilde JSON:API. Een integratieleverancier was al uitgegaan van REST. De product owner wilde gewoon dat de mobiele app niet langer hoefde te wachten op website-releases.

Die kleine vraag klinkt meestal technisch. Dat is ze niet. Het is een governancevraag, een budgetvraag en soms een wervingsvraag in een ontwikkelaarshoodie.

Drupal kan een zeer capabele backend zijn voor decoupled producten. Het heeft al gestructureerde content, rollen, rechten, workflows, revisies, vertalingen, mediabeheer, taxonomie en een volwassen module-ecosysteem. Het lastige deel is beslissen hoe die content Drupal verlaat. Drupal core heeft native ondersteuning voor JSON:API, GraphQL is beschikbaar via een contributed module, en Drupal’s RESTful Web Services-module blijft een optie voor aangepaste resource-achtige endpoints. Drupal’s eigen documentatie over decoupled architecturen zegt het onderscheid duidelijk: JSON:API zit in core, GraphQL is contributed, en Drupal kan content via API’s beschikbaar stellen aan een externe frontend.

En toch blijven teams slechte keuzes maken.

Ze kiezen GraphQL omdat het modern klinkt. Ze kiezen REST omdat iedereen het heeft gebruikt. Ze kiezen JSON:API omdat het er is. Geen van die dingen is een strategie.

Hier is de scherpere versie: voor de meeste contentplatformen met Drupal als backend zou JSON:API het standaard startpunt moeten zijn. GraphQL moet verdiend worden. REST moet worden gereserveerd voor gevallen waarin de andere twee te breed of te uitgesproken in hun aannames zijn.

Dat zal sommige mensen irriteren. Goed.

Begin met de saaie winnaar: JSON:API

JSON:API is saai op de best mogelijke manier.

Drupal’s core JSON:API-module implementeert de JSON:API-specificatie voor Drupal-entiteiten. Het biedt een zero-configuration, opinionated manier om CRUD-operaties voor sitecontent beschikbaar te maken, en is gekoppeld aan Drupal’s Entity API, Field API, caching-, authenticatie- en autorisatiesystemen.

Die zin bevat het deel waar bestuurders om zouden moeten geven: core module.

Core doet ertoe. Core betekent meestal minder verrassingen van leveranciers, eenvoudiger onderhoudsplanning, een duidelijkere security posture en minder risico van het type “we hebben die ene contractor nodig die de aangepaste API-laag begrijpt”. Drupal’s JSON:API-documentatie zegt dat de module API’s rond entiteitstypen en bundles beschikbaar maakt, en filtering, includes, paginering, sortering, revisies, vertalingen, GET, POST, PATCH, DELETE, bestandsuploads en resource-aanpassing via events ondersteunt.

Een praktisch voorbeeld: stel je een mediabedrijf voor met artikelen, auteurs, onderwerpen, teasers voor landingspagina’s en afbeeldingen. Het frontendteam heeft artikelpagina’s in Next.js nodig. De mobiele app heeft dezelfde artikeltekst, hero-afbeelding, auteursnaam en gerelateerde onderwerpen nodig. JSON:API kan die Drupal-entiteiten beschikbaar maken zonder dat het backendteam vanaf nul een API-taal hoeft te bedenken. Gerelateerde resources kunnen via includes worden ingesloten, en collecties kunnen worden gefilterd of gepagineerd.

Is de payload mooi? Soms. Soms lijkt het alsof een commissie hem na een lange lunch heeft ontworpen.

Maar dat is ook precies het punt. JSON:API is een specificatie, niet de persoonlijke smaak van een ontwikkelaar. De officiële JSON:API-site beschrijft het als een specificatie voor het bouwen van API’s in JSON, met gedeelde conventies die discussies over de vorm van responses verminderen en teams helpen algemene tooling te gebruiken. Het media type is application/vnd.api+json, en versie 1.1 werd afgerond op 30 september 2022.

Hier zit een verborgen managementvoordeel. Een gestandaardiseerd responseformaat betekent dat onboarding minder afhankelijk is van tribal knowledge. Een nieuwe frontendontwikkelaar kan nog steeds vloeken op de geneste structuur van data, attributes en relationships. Prima. In ieder geval vloekt diegene op iets dat gedocumenteerd is.

De valkuil die niemand wil noemen

JSON:API stelt Drupal’s contentmodel behoorlijk direct beschikbaar. Dat kan een kracht zijn, vooral wanneer Drupal de redactionele source of truth is. Het kan ook te veel van Drupal’s interne vorm naar de frontend lekken.

Als je contentmodel schoon is, voelt JSON:API efficiënt. Als je contentmodel een museum van oude compromissen is, maakt JSON:API de rommel zichtbaar.

Ik heb “Article”-contenttypes gezien met velden zoals field_new_body_2021, field_mobile_summary, field_legacy_related en field_do_not_use. JSON:API verandert dat niet magisch in een elegante product-API. Het stelt het model beschikbaar dat je daadwerkelijk hebt. Misschien een beetje wreed. Maar wel nuttig.

Drupal’s documentatie maakt ook een grens duidelijk: JSON:API behandelt entity-oriented CRUD, maar businessregels zoals login, wachtwoordreset en accountcreatie vallen buiten de taak van JSON:API. Als je applicatie domeinacties nodig heeft zoals “leverancier goedkeuren”, “verlengingsquote berekenen” of “claim indienen”, forceer die dan niet in content-entity endpoints alleen omdat de module handig is.

Die route wordt snel lelijk.

GraphQL voelt elegant omdat het de pijn verplaatst

GraphQL is verleidelijk. De frontend vraagt precies de velden op die hij wil. De response heeft dezelfde vorm als de query. Het heeft een getypeerd schema. Het voelt ontworpen voor component-based frontends omdat het dat, eerlijk gezegd, ook was. De officiële GraphQL-site beschrijft GraphQL als een open-source querytaal en server-side runtime voor API’s met een sterk getypeerd schema, en laat zien dat de client geselecteerde velden opvraagt in plaats van een vaste serverresponse te ontvangen.

Voor frontendteams is dat een echte verbetering.

Neem een homepage die uit componenten bestaat: hero, uitgelichte artikelen, events, sponsorplekken, navigatie, regionale meldingen. Met REST kan de frontend meerdere endpoints aanroepen. Met JSON:API kan hij een collectie opvragen en gerelateerde resources includen, maar de structuur volgt nog steeds entiteitsrelaties. Met GraphQL kan de query dichter bij het scherm liggen. Dat is belangrijk wanneer teams productoppervlakken snel opleveren.

Drupal’s GraphQL-module laat ontwikkelaars een GraphQL-schema voor Drupal 10 en 11 maken en beschikbaar stellen. De module is gebouwd rond webonyx/graphql-php, ondersteunt de officiële GraphQL-specificatie, bevat GraphiQL op /graphql/explorer, en geeft ontwikkelaars data producer plugins plus aangepaste code voor schemawerk.

Lees de formulering zorgvuldig: “maken en beschikbaar stellen”.

De huidige Drupal GraphQL-module is geen magische spiegel die simpelweg elk Drupal-veld reflecteert in een nette API. Drupal.org zegt dat de oudere 3.x-versie automatisch een schema genereerde vanuit Drupal-entiteiten en Drupal-details via de API blootlegde, terwijl 4.x het schemaontwerp aan de ontwikkelaar overlaat zodat Drupal-internals verborgen kunnen worden. Dezelfde pagina zegt dat 4.x vereist dat de ontwikkelaar het schema opzet en mapt.

Dat is geen voetnoot. Dat is de factuur.

GraphQL kan je een schoon contract geven tussen product en contentopslag. Maar iemand moet dat contract ontwerpen. Iemand moet het onderhouden wanneer redacteuren velden toevoegen, wanneer het design system verandert, wanneer personalisatie arriveert, wanneer legal regionale toestemmingslogica vraagt, wanneer het mobiele team offline synchronisatie nodig heeft.

Eigenlijk is dat te beleefd. Iemand moet er eigenaar van zijn. Ownership is de ontbrekende regelpost in veel GraphQL-voorstellen.

Wanneer GraphQL de kosten waard is

GraphQL is zinvol wanneer de API een product op zichzelf is.

Een grote universiteit met tientallen microsites, een studentenapp, digital signage, faculteitsprofielen, cursuscatalogi en een design system kan profiteren van een GraphQL-laag. De consumenten zijn divers. De content graph is diep. Frontendteams hebben selectieve toegang nodig. De organisatie wil misschien een API-contract dat de eigenaardigheden van Drupal-bundles verbergt.

GraphQL past ook wanneer Drupal slechts één bron tussen meerdere is. Misschien komt content uit Drupal, prijzen uit een ERP, beschikbaarheid uit een boekingsengine en gebruikersrechten uit een CRM. GraphQL kan clients een coherent schema presenteren terwijl resolvers gegevens uit verschillende systemen ophalen. Het GraphQL-model is gebouwd rond een sterk getypeerd schema en een door de client gespecificeerde responsevorm, en precies daarom werkt het goed in dit soort compositielaag.

Maar voor een normale marketingsite met een headless frontend? Ik zou sceptisch zijn. Zelfs licht geïrriteerd.

Als de werkelijke behoefte is “React moet artikelen uit Drupal lezen”, kan GraphQL een verkleedfeest zijn. Je geeft architectuurgeld uit om te vermijden dat je JSON:API-includes en filters leert. Erger nog, je creëert misschien een bespoke API-laag die slechts twee ontwikkelaars begrijpen.

De Drupal GraphQL-projectpagina meldt dat stabiele releases onder Drupal’s security advisory policy vallen en somt recente releases voor Drupal 10 en 11 op, waaronder 8.x-4.14 uitgebracht op 29 april 2026 en een 5.0.0 beta voor Drupal 10.4 en 11. Dat is gezond. Het neemt het ontwerpwerk niet weg.

Een contributed module kan volwassen zijn en toch de verkeerde default zijn.

RESTful Web Services: oud, nuttig en meestal overmatig gebruikt

REST is zo’n woord geworden dat betekent wat de spreker nodig heeft dat het betekent. Soms betekent het schone resource-oriented HTTP. Soms betekent het “we retourneren JSON uit een controller”. Soms betekent het “de leverancier gaf ons een endpoint en een PDF”.

Roy Fielding’s proefschrift introduceerde REST als een architectuurstijl voor gedistribueerde hypermediasystemen, met constraints zoals client-server-scheiding, stateless communicatie, cache, een uniforme interface, gelaagde systemen en optionele code-on-demand. Dat oorspronkelijke idee is strikter dan veel van wat in projectplannen REST wordt genoemd.

Drupal’s RESTful Web Services-module is nuttig omdat hij resources kan blootstellen met specifieke methoden, serialisatieformaten en authenticatie. Drupal-studiemateriaal beschrijft REST-resources voor entiteiten, ondersteuning voor methoden zoals GET, POST, PATCH en DELETE, JSON- of XML-serialisatie, en authenticatie via Basic Auth, cookies of andere modules zoals OAuth. Het merkt ook op dat onveilige methoden een X-CSRF-Token request header vereisen.

Dit maakt REST geschikt voor smal integratiewerk.

Een payment provider post transactiestatus naar Drupal. Een warehousesysteem haalt een lijst met bijgewerkte producthandleidingen op. Een partnerportaal heeft één zorgvuldig gevormd endpoint nodig voor goedgekeurde assets. Een legacy mobiele app verwacht al /api/v1/articles/{id} en kan dit kwartaal niet herschreven worden.

REST geeft je controle. Het geeft je ook het lege-pagina-syndroom.

Anders dan bij JSON:API, waar conventies al gekozen zijn, vraagt een aangepast REST-endpoint om beslissingen: URL-vorm, responseformaat, foutformaat, pagineringsstijl, filtersyntaxis, versioning, authenticatie, cache headers, documentatie, deprecation policy. OpenAPI kan helpen om dat oppervlak te documenteren, en de OpenAPI Specification is een standaard, taalonafhankelijke manier om HTTP API’s te beschrijven zodat mensen en computers ze kunnen begrijpen zonder broncode te lezen.

Toch moet je de keuzes maken.

En die keuzes blijven hangen. Een slordig endpoint dat in week twee is ontworpen, kan het product jarenlang achtervolgen omdat een appversie in het wild er nog steeds van afhankelijk is.

De beslissing is niet “welke API is het beste?”

Dat frame is lui. Sorry, maar dat is het.

De betere vraag is: welk soort koppeling kan je organisatie zich veroorloven?

JSON:API koppelt consumenten aan Drupal’s entiteitsmodel. Dat is vaak acceptabel wanneer Drupal het belangrijkste contentsysteem is en de frontend een vervangende presentatielaag is. De beloning is snelheid en minder backend-uitvinding.

GraphQL koppelt consumenten aan een schema dat door je team is ontworpen. Goed gedaan verbergt dat schema Drupal en drukt het het productdomein uit. Slecht gedaan wordt het een tweede CMS-model dat in code wordt onderhouden.

REST koppelt consumenten aan aangepaste endpoints. Dat is uitstekend voor specifieke integraties en gevaarlijk voor brede contentlevering, omdat elk endpoint een miniatuurproduct wordt met zijn eigen onderhoudsstaart.

Hier is de versie die ik aan een executive steering group zou voorleggen.

Tabellen zijn een beetje steriel, maar deze bespaart meetings.

Waar projectmanagers op moeten letten

De API-keuze verandert het projectplan meer dan mensen toegeven.

Met JSON:API is contentmodellering het kritieke pad. Als het contentmodel doordacht is, kan het API-werk snel gaan. Als het contentmodel chaotisch is, vertraagt frontendontwikkeling omdat elke query weer een redactioneel compromis blootlegt. Zet senior aandacht op veldnaamgeving, herbruikbare paragraph patterns, mediarelaties, taxonomie en rechten voordat het frontendteam pagina’s begint te bedraden.

Met GraphQL is schema-ownership het kritieke pad. Wie ontwerpt het schema? Wie reviewt breaking changes? Wie schrijft resolvers? Wie behandelt performanceproblemen zoals geneste queries die te veel backend-loads veroorzaken? De Drupal GraphQL-module biedt tools en extension points, inclusief data producer plugins en GraphiQL, maar neemt de noodzaak van backend engineering discipline niet weg.

Met REST is contractdiscipline het kritieke pad. Elk endpoint heeft documentatie, tests, authenticatieregels, foutsemantiek en een versioning-verhaal nodig. REST lijkt goedkoop wanneer het eerste endpoint gebouwd is. Het vijfde endpoint vertelt de waarheid.

Nog iets. Authenticatie wordt vaak onderschat. Drupal JSON:API is gekoppeld aan Drupal’s authenticatie- en autorisatiesystemen, en REST kan authenticatieproviders gebruiken zoals Basic Auth en cookies, waarbij OAuth vaak via contributed modules wordt toegevoegd. De Lupus Decoupled Drupal-documentatie wijst op Simple OAuth als een manier om API-requests met een token te authenticeren in decoupled setups.

Laat dat niet liggen tot de sprint voor launch. Die sprint is al vervloekt.

Performance: het argument dat iedereen simplificeert

GraphQL-fans zeggen dat het over-fetching voorkomt. Klopt. JSON:API-fans zeggen dat includes round trips verminderen. Ook waar. REST-fans zeggen dat HTTP-caching eenvoudig is. Opnieuw waar.

Nu het onaangename deel: alle drie kunnen snel zijn, en alle drie kunnen traag zijn.

GraphQL kan payloadgrootte verminderen, maar complexe geneste queries kunnen de backend straffen als resolvers slordig zijn. JSON:API kan Drupal’s response caching en includes gebruiken, maar payloads kunnen breedsprakig zijn. REST kan netjes naar HTTP-caching mappen, maar aangepaste endpoints vergeten cacheability vaak totdat performance testing begint. Fielding’s REST-constraints omvatten cache omdat cache netwerkverkeer en latency kan verminderen, maar verouderde data en cache-invalidation blijven echte trade-offs. Drupal’s JSON:API-documentatie koppelt de module expliciet aan Drupal response caching, terwijl de GraphQL-module op Drupal.org is gecategoriseerd onder Decoupled, Developer tools en Performance.

Dus nee, GraphQL is niet automatisch de “performance-optie”.

De eerste performancewinst is meestal betere contentmodellering. De tweede is een cachestrategie. De derde is het vermijden van dom clientgedrag, zoals twaalf keer hetzelfde endpoint aanroepen omdat niemand een data access layer heeft geschreven.

Glamoureus? Nee. Effectief? Ja.

Een bot selectiekader

Als ik een founder of CTO zou adviseren, zou ik met deze volgorde beginnen.

Ten eerste: gebruik Drupal’s normale gerenderde pagina’s tenzij je een reden hebt om te decouplen. Decoupling voegt complexiteit toe op het gebied van hosting, preview, routing, cache, deployment, authenticatie en debugging. Drupal’s eigen decoupled documentatie onderscheidt standaard Drupal van decoupled Drupal door op te merken dat layout naar de frontend verhuist en de backend content via API’s beschikbaar stelt. Die verschuiving is niet gratis.

Ten tweede: als je vooral decouplet voor een moderne frontend, begin dan met JSON:API. Bouw één echte pagina, geen demo. Neem media, menu’s of navigatie, gerelateerde content, previewbehoeften, authenticatie indien nodig en cachegedrag mee. Je leert meer van één lelijke pagina dan van zes architectuurdiagrammen.

Ten derde: stap pas over op GraphQL wanneer de consumer experience het schemawerk rechtvaardigt. Goede redenen zijn meerdere frontendconsumenten, de noodzaak om Drupal-internals te verbergen, complexe content graphs of aggregatie over systemen heen. Slechte redenen zijn “onze frontendontwikkelaar houdt van Apollo” en “in het investor deck staat GraphQL”.

Ten vierde: gebruik REST voor integraties die strakke grenzen nodig hebben. Een aangepast endpoint voor een partnerexport kan netjes zijn. Een heel contentplatform dat uit handgemaakte endpoints bestaat, kan veranderen in een lade vol ongelabelde sleutels.

En ruim het Drupal-model op. Alsjeblieft. Geen enkele API-laag kan een contentmodel volledig redden waarvan niemand eigenaar is.

De politiek van “future-proof”

Bestuurders houden van de term “future-proof”. Ik begrijp waarom. Niemand wil een backend rebuild goedkeuren en achttien maanden later horen dat de gekozen API het bedrijf in een hoek heeft gezet.

Maar future-proofing gaat meestal minder over het kiezen van de meest fancy API en meer over kiezen waar verandering mag plaatsvinden.

JSON:API zegt: “Drupal’s model is het contract.” Dat is eerlijk en snel.

GraphQL zegt: “Ons productschema is het contract.” Dat is krachtig en duur.

REST zegt: “Dit endpoint is het contract.” Dat is precies en makkelijk te vermenigvuldigen tot een onderhoudsprobleem.

Er is geen universele winnaar. Er is alleen fit.

Mijn bias is simpel: begin met het minst aangepaste dat het product kan ondersteunen. In Drupal betekent dat meestal JSON:API. Voeg GraphQL toe wanneer je de owner en het budget kunt benoemen. Voeg REST toe wanneer de integratie specifiek genoeg is om een eigen deur te verdienen.

De slechtste keuze is de keuze die uit mode wordt gemaakt, want mode komt nooit opdagen voor onderhoud.

Op zoek naar het nummer 1 Drupal-ontwikkelingsbedrijf op de markt? Je hebt het zojuist gevonden.

Wij zijn het beste digitale bureau met focus op Drupal, gebouwd om snelle, veilige en schaalbare platforms te leveren — zonder compromissen. Van nieuwe builds en redesigns tot migraties en langdurige support: onze Drupal-experts leveren resultaten op enterprise-niveau met boutique-level aandacht.

Boek vandaag nog een call en laten we je Drupal-roadmap omzetten in een high-performing realiteit.