Wat is GraphQL? Uitleg, voorbeeld en verschil met REST

GraphQL is een querytaal voor API's, met een runtime die zulke query's uitvoert. Je stuurt één request naar één endpoint en beschrijft daarin precies welke gegevens je wilt hebben. De server stuurt alleen die velden terug, als JSON, en niets meer.

Facebook ontwikkelde GraphQL in 2012 en maakte het in 2015 open source. Sinds 2019 is de GraphQL Foundation, onder de vleugels van de Linux Foundation, het neutrale thuis van GraphQL. Je komt de naam ook tegen als graph ql of GraphQL API. In dit artikel lees je hoe GraphQL werkt, hoe een query met antwoord eruitziet, wat het verschil met REST is en wanneer je beter iets anders kiest.

Wat is GraphQL?

GraphQL is een taal waarmee een app gegevens opvraagt bij een server. QL staat voor query language. Graph verwijst naar hoe GraphQL naar data kijkt: als een netwerk van objecten die naar elkaar verwijzen. Een order verwijst naar een klant, de klant naar zijn adressen en de order naar zijn orderregels.

Wie een GraphQL API aanbiedt, beschrijft in een schema welke objecten er zijn en welke velden ze hebben. De app die de gegevens nodig heeft, de client, stelt op basis van dat schema een query samen. Zo bepaalt de client de vorm van het antwoord, en niet de server. Weet je nog niet precies wat een API doet, lees dan eerst wat een API is.

Querytaal, maar geen database

De naam doet denken aan SQL, maar GraphQL bewaart zelf geen data. Het zit tussen de app en de plekken waar de data echt staan: een database, een andere API of een bestaande dienst. Welke opslag en welke programmeertaal je daarachter gebruikt, laat de GraphQL-specificatie vrij. Er bestaan servers in onder meer JavaScript, Go, Python, PHP en Java.

Hoe werkt GraphQL?

Elke GraphQL API draait om drie onderdelen:

• Het schema. Een beschrijving van alle types en velden die je kunt opvragen, met per veld het type: tekst, getal, lijst of een ander object. Een uitroepteken achter het type betekent dat het veld altijd een waarde heeft.
• De operatie. Een query leest gegevens. Een mutation wijzigt ze, bijvoorbeeld een product in een winkelwagen zetten. Een subscription houdt een verbinding open en stuurt nieuwe gegevens zodra er iets verandert.
• De resolvers. Per veld een functie op de server die de waarde ophaalt, uit een database of uit een andere dienst.

Zo ziet een stukje schema eruit, ingekort uit de GraphQL API van Afosto:

type Order {
  number: String!
  status: State!
  customer: Customer
  items: [OrderItem!]!
}

Een request doorloopt vier stappen. De server leest de query, controleert hem tegen het schema, laat de resolvers de velden vullen en stuurt het resultaat terug in dezelfde vorm als de query. Vraag je een veld op dat niet in het schema staat, dan weigert de server de query voordat hij iets ophaalt. Een tikfout zie je dus al tijdens het bouwen, niet pas in productie.

Voorbeeld van een GraphQL-query met antwoord

Hieronder staat een echte query op de GraphQL API van Afosto. Hij vraagt bij één order het ordernummer, de status, de voornaam van de klant en de orderregels op, met per regel de naam en het aantal. De variabele $id geef je los mee, zodat dezelfde query voor elke order werkt.

query Bestelling($id: String!) {
  order(id: $id) {
    number
    status
    customer {
      contact {
        given_name
      }
    }
    items {
      label
      quantity
    }
  }
}

Dit antwoord kwam terug uit een testomgeving. Het heeft precies de vorm van de query:

{
  "data": {
    "order": {
      "number": "ODR-10000134",
      "status": "OPEN",
      "customer": {
        "contact": { "given_name": "Floor" }
      },
      "items": [
        { "label": "Verzenddoos Medium (30x20x15cm)", "quantity": 2 },
        { "label": "USB-C kabel 1 meter gevlochten", "quantity": 1 }
      ]
    }
  },
  "extensions": {
    "complexity": { "complexity": 9, "complexity_limit": 400 }
  }
}

Drie dingen vallen op:

1. Eén request voor drie soorten gegevens. Order, klant en orderregels komen in één antwoord. Bij een REST API haal je die vaak met twee of drie aparte calls op.
2. Alleen wat je vroeg. Een order heeft veel meer velden, zoals adressen, betalingen en totalen. Die komen niet mee, omdat de query ze niet noemt.
3. Een rekensom voor de server. In extensions meldt de Afosto API hoe zwaar deze query was (9) en waar de grens ligt (400). Zo beschermt een GraphQL-server zich tegen query's die te veel tegelijk opvragen.

GraphQL vs REST: wat is het verschil?

REST is een architectuurstijl voor API's, GraphQL een querytaal met een eigen runtime. Ze lossen hetzelfde probleem op: een app wil gegevens ophalen en wijzigen bij een server. De aanpak verschilt.

Bij REST heeft elke soort gegevens een eigen URL, zoals /orders/123 of /customers/45. De server bepaalt wat je per URL terugkrijgt. Bij GraphQL gaat alles naar één endpoint, meestal /graphql, en bepaal je zelf wat er in het antwoord staat.

Over-fetching en under-fetching

Een REST-endpoint geeft altijd hetzelfde pakket terug. Heb je alleen de naam en het e-mailadres van een klant nodig, dan krijg je toch het hele klantprofiel. Dat heet over-fetching.

Het omgekeerde komt ook voor. Je wilt een order met de klant en de producten, maar het endpoint geeft alleen id's terug, dus doe je nog twee calls. Dat heet under-fetching. Met GraphQL vraag je in één keer op wat je nodig hebt. Dat scheelt vooral op een mobiele verbinding, waar elke extra call wachttijd kost.

Versies en documentatie

Bij REST bouw je vaak een nieuwe versie van de API als de vorm van een antwoord verandert. Bij GraphQL voeg je velden toe zonder dat bestaande query's breken, want elke client vraagt alleen de velden op die hij kent. Een oud veld markeer je met @deprecated, zodat ontwikkelaars zien dat het gaat verdwijnen.

Het schema dient ook als documentatie. Tools als GraphiQL lezen het uit en tonen per type welke velden er zijn, met autocomplete terwijl je typt. Bij REST zoek je die informatie meestal op in een losse specificatie, vaak in het OpenAPI-formaat.

De voordelen van GraphQL op een rijtje

• Precies de data die je nodig hebt, niet meer en niet minder.
• Eén request voor gerelateerde gegevens, ook als die uit verschillende bronnen komen.
• Een schema met types, zodat je een fout in een query ziet voordat je hem uitvoert.
• Doorbouwen zonder nieuwe versies, want nieuwe velden breken bestaande query's niet.
• Ingebouwde documentatie, plus tools als GraphiQL om query's interactief uit te proberen.
• Frontend en backend werken los van elkaar. Het frontendteam bouwt een nieuw scherm met de velden die er al zijn, zonder te wachten op een nieuw endpoint.

Nadelen van GraphQL: wanneer kies je het niet?

GraphQL lost niet elk probleem op. Twee nadelen gaan over de server:

• Caching. Alle query's gaan naar dezelfde URL, dus gewone HTTP-caching werkt niet vanzelf. Clients als Apollo Client en Relay cachen daarom per object, op basis van een uniek id.
• Zware query's. Een client kan diep geneste query's sturen die de server veel werk geven. Een GraphQL-server heeft daarom grenzen nodig, zoals een maximale diepte of een complexiteitslimiet. In de beveiligingsrichtlijnen van graphql.org lees je welke maatregelen gebruikelijk zijn.

Daarnaast vraagt GraphQL meer van je team:

• Foutafhandeling. Een antwoord kan gegevens én fouten tegelijk bevatten. Faalt één veld, dan staat de rest van het antwoord er nog in en staat de fout in de lijst errors. Monitoring die alleen naar HTTP-statuscodes kijkt, mist dat.
• Leercurve en opzet. Een schema ontwerpen en resolvers schrijven kost bij een kleine API meer tijd dan een paar REST-endpoints.
• Bestanden. Voor uploads en downloads gebruik je in de praktijk vaak een gewone HTTP-route naast je GraphQL API.

Een vuistregel: heb je een eenvoudige API met vaste antwoorden, zoals een export of een webhook, dan volstaat REST meestal. Halen verschillende apps of schermen elk andere combinaties van gegevens op, dan wint GraphQL. Veel platforms bieden daarom allebei aan.

GraphQL en headless commerce

Bij een headless webshop staat de voorkant los van het systeem erachter. Je bouwt de frontend zelf, bijvoorbeeld in React, en haalt producten, prijzen en voorraad op via een API. Hoe die opzet werkt, lees je in wat een headless CMS is.

GraphQL past daar goed bij. Een productpagina heeft de naam, de foto's, de prijs en de voorraad nodig, een winkelwagen weer andere velden. Met GraphQL haalt elk scherm in één request op wat het toont. Omdat het schema types heeft, ziet je editor bovendien meteen of een veld bestaat.

Het lastige deel zit vaak niet in de frontend, maar in wat er na de bestelling gebeurt. De order moet naar het magazijn, de voorraad moet ook in de winkel en op bol kloppen, en de factuur moet naar de boekhouding. Werkt de webshop los van de rest, dan heb je voor elk van die stappen een koppeling nodig.

Zo werkt GraphQL bij Afosto

Afosto is een platform voor retailers en groothandels, met winkels, webshops, voorraad en orders op één plek. De GraphQL API van Afosto draait op afosto.app/graphql. Op dat adres staat ook een playground met de documentatie van het schema. Je verbindt hem met je Afosto-account en probeert query's en mutations uit op je eigen gegevens. Let op: een mutation in de playground wijzigt je echte gegevens.

Bouw je een eigen frontend, dan gebruik je de Storefront JavaScript Client. Die levert kant-en-klare query's, mutations en fragmenten voor de winkelwagen, de checkout en orders, en je voegt er eigen query's aan toe. Je frontend werkt met een storefront-token dat bij één verkoopkanaal hoort.

In de client zet addCartItems een product in de winkelwagen, en confirmCart maakt van die winkelwagen een order. Die order komt in hetzelfde orderoverzicht als de orders uit je kassa en van marktplaatsen. Vanaf daar loopt hij als elke andere order: voorraad reserveren, picken en factureren. Naast GraphQL heeft Afosto ook REST-endpoints, bijvoorbeeld om het openstaande saldo van een zakelijke klant op te vragen.

Bouw je een headless webshop voor een retailer of groothandel? Met Afosto beheer je winkels, webshops, voorraad en orders vanuit één platform, en praat je frontend met één GraphQL API. Maak een account en probeer je eerste query in de playground, of plan een demo als je het eerst wilt zien.

GraphQL leren en uitproberen

Wil je zelf met GraphQL aan de slag, dan zijn dit goede eerste stappen:

1. Lees de basis in de officiële uitleg op graphql.org: query's, mutations, schema's en types.
2. Verken een echte API in een playground of in GraphiQL, de browser-IDE voor GraphQL. Typ een query, gebruik autocomplete en lees in het schema welke velden er zijn.
3. Kies een client voor je frontend, zoals Apollo Client of Relay, of gebruik gewoon fetch met een POST-request naar het endpoint.
4. Regel de beveiliging voordat je een eigen server live zet: authenticatie, timeouts en limieten op diepte en complexiteit.

Veelgestelde vragen

Wat is het verschil tussen GraphQL en REST?

REST is een architectuurstijl waarbij elke soort gegevens een eigen URL heeft en de server bepaalt wat je terugkrijgt. GraphQL is een querytaal: je stuurt alle verzoeken naar één endpoint en beschrijft zelf welke velden je wilt. Zo haal je gerelateerde gegevens in één request op, zonder te veel of te weinig data. REST is daarentegen eenvoudiger te cachen en volstaat vaak voor simpele API's.

Is GraphQL een database?

Nee. GraphQL is een querytaal voor API's en bewaart zelf geen gegevens. Een GraphQL-server zit tussen de app en de bronnen waar de data staan, zoals een database, een andere API of een bestaande dienst. Per veld haalt een resolver de waarde op uit die bron. Welke database of programmeertaal je daarachter gebruikt, laat GraphQL vrij.

Wat is een GraphQL resolver?

Een resolver is een functie op de server die de waarde van één veld ophaalt. Vraagt een query om een order met de klant en de orderregels, dan haalt de ene resolver de order op, een tweede de klant en een derde de orderregels. Samen vullen ze het antwoord in precies de vorm van de query. Faalt één resolver, dan kan de rest van het antwoord nog steeds gegevens bevatten.

Wat is het verschil tussen GraphQL en React?

GraphQL is een manier om gegevens op te vragen bij een API. React is een JavaScript-bibliotheek waarmee je de gebruikersinterface van een app of website bouwt. Ze vervangen elkaar dus niet, maar werken vaak samen: een React-app haalt met een GraphQL-client zoals Apollo Client of Relay precies de gegevens op die een scherm toont.

Wat is een mutation in GraphQL?

Een mutation is een GraphQL-operatie die gegevens wijzigt, zoals een product in een winkelwagen zetten of een adres bijwerken. Een query leest alleen. Net als bij een query geef je bij een mutation aan welke velden je in het antwoord terug wilt, zodat je na de wijziging meteen de nieuwe stand hebt. Zo neemt een mutation de rol over van POST, PUT en DELETE bij REST.

Wat is GraphiQL?

GraphiQL is een opensource ontwikkelomgeving in de browser waarmee je een GraphQL API verkent. Je typt een query met autocomplete, voert hem uit en ziet het antwoord ernaast. GraphiQL leest het schema uit, zodat je per type ziet welke velden er zijn. Veel API's bieden een vergelijkbare playground aan, zoals de GraphQL API van Afosto op afosto.app/graphql.