GraphQL
De REST API Design Rules en de OpenAPI Specification staan op de 'pas toe of leg uit'-lijst met een toepassingsgebied dat op REST is gescoped: respectievelijk "het aanbieden van REST API's" en "het beschrijven/specificeren van een REST API". Voor een GraphQL-API gelden ze dus niet, en Forum Standaardisatie stelt bij de ADR expliciet dat de standaard "niet het gebruik van REST-API's verplicht". De inzet van GraphQL is daarmee een eigen afweging per organisatie, zonder verplichting om die te verantwoorden, maar ook zonder vastgesteld kader: een NLGov-profiel of toetsingskader voor GraphQL bestaat niet. Een uitgebreide afweging, inclusief de voor- en nadelen ten opzichte van REST, staat in de vierdelige blogserie "GraphQL onder de loep" op deze site.
GraphQL is een querytaal voor API's, gecombineerd met een runtime die queries uitvoert tegen een sterk getypeerd schema. De client beschrijft per request exact welke velden hij nodig heeft en krijgt precies die data terug, via één endpoint. GraphQL is in 2012 ontwikkeld bij Facebook, in 2015 open source gemaakt en wordt sinds eind 2018 beheerd door de GraphQL Foundation, onderdeel van de Linux Foundation. De actuele versie van de specificatie is de September 2025 Edition, de eerste nieuwe editie sinds oktober 2021.
Hoe het werkt
Het hart van een GraphQL-API is het schema, geschreven in de Schema Definition Language (SDL). Clients stellen daar queries op samen die qua vorm het antwoord spiegelen:
type Api {
id: ID!
titel: String!
versie: String!
}
type Query {
api(id: ID!): Api
}
query Api($id: ID!) {
api(id: $id) {
titel
versie
}
}
Naast queries (lezen) kent GraphQL mutations (schrijven) en subscriptions (server-push bij wijzigingen).
Kenmerken
- Sterk getypeerd contract. Het schema beschrijft alle types, velden en operaties en is via introspectie machineleesbaar op te vragen. Daarop bouwt een ecosysteem van tooling: interactieve explorers, documentatiegeneratoren en codegeneratie voor clients.
- Client-gestuurde selectie. De client bepaalt per request welke velden de response bevat. GraphQL is ontworpen om zowel over- als underfetching te voorkomen, oorspronkelijk voor mobiele toepassingen met uiteenlopende schermen en beperkte bandbreedte.
- Eén endpoint over HTTP. Al het verkeer loopt doorgaans via één endpoint. Het transportgedrag wordt beschreven in de GraphQL over HTTP-specificatie, op het moment van schrijven (medio 2026) een working draft.
- Evolutie via deprecation. Velden worden met
@deprecatedgemarkeerd en op basis van gemeten gebruik uitgefaseerd; versioneren is ongebruikelijk. Omdat elke query benoemt welke velden hij opvraagt, is per afnemer meetbaar wat nog in gebruik is.
Aanvullende specificaties en conventies
- GraphQL Cursor Connections: de gangbare conventie voor paginering.
- Persisted operations-RFC: standaardisatie van vooraf geregistreerde queries.
- Cost directives (IBM, draft): een gedeelde taal voor querykosten.
- Composite Schemas-werkgroep: leveranciersneutrale federatie van schema's.
- Register van scalar-specificaties: custom
scalars, te refereren via de
@specifiedBy-directive.