Wat is GraphQL?

Definitie: GraphQL is een querytaal voor API’s en een bijbehorende serveromgeving waarmee een applicatie precies de gegevens opvraagt die ze nodig heeft, via één centraal endpoint. Het is ontwikkeld door Facebook en wordt vaak gebruikt als alternatief voor REST, vooral bij applicaties met veel onderling verbonden gegevens.

In het kort

• Facebook begon in 2012 intern met GraphQL en maakte het in 2015 openbaar als open source.
• De client bepaalt zelf welke velden hij terugkrijgt. Dat voorkomt dat je te veel of te weinig gegevens ophaalt.
• Lezen gebeurt met queries, wijzigen met mutations en realtime updates met subscriptions.
• REST is eenvoudiger en makkelijker te cachen; GraphQL is flexibeler bij complexe, samenhangende gegevens.

Wat is GraphQL?

GraphQL is een manier om met een API te praten. Bij een gewone REST API heeft elk soort gegeven een eigen adres: één voor klanten, één voor bestellingen, één voor producten. Bij GraphQL is er één adres. Je stuurt daar een vraag naartoe waarin je precies beschrijft welke gegevens je wilt, en je krijgt een antwoord met precies die structuur terug.

Een voorbeeld. Een app wil een overzicht tonen met de naam van een klant, zijn laatste drie bestellingen en per bestelling de status. Bij REST zijn daar vaak meerdere verzoeken voor nodig: eerst de klant ophalen, dan de bestellingen, dan per bestelling de details. Bij GraphQL schrijf je één query die klant, bestellingen en status in één keer opvraagt, met alleen de velden die op het scherm komen.

De naam verwijst naar de graaf, de structuur van gegevens die met elkaar verbonden zijn. Klanten hebben bestellingen, bestellingen hebben producten, producten hebben leveranciers. GraphQL laat je door die verbindingen heen vragen.

Waar komt GraphQL vandaan?

Volgens Moesif is het begin van GraphQL terug te voeren op 2012, toen ontwikkelaars bij Facebook zochten naar een efficiëntere manier om gegevens op te halen voor de mobiele apps. In 2015 maakte Facebook GraphQL openbaar. Sindsdien wordt het door veel bedrijven gebruikt. GFU noemt onder meer GitHub, Shopify en Airbnb.

REST is ouder. Moesif vermeldt dat Roy Fielding de architectuurstijl in 2000 beschreef in zijn proefschrift. REST is nog altijd de meest gebruikte vorm van web-API’s.

Hoe werkt GraphQL?

Een GraphQL API bestaat uit een paar vaste onderdelen:

• Schema. Een beschrijving van alle gegevenstypen en hun velden, zoals een klant met naam, e-mail en bestellingen. Het schema is sterk getypeerd: van elk veld ligt vast of het tekst, een getal, een datum of een lijst is.
• Query. Een vraag om gegevens op te halen, met precies de velden die je nodig hebt.
• Mutation. Een opdracht om gegevens te wijzigen, zoals een bestelling aanmaken of een status aanpassen.
• Subscription. Een abonnement op wijzigingen, zodat de server realtime een bericht stuurt als er iets verandert.
• Resolvers. De code op de server die per veld bepaalt waar de gegevens vandaan komen, bijvoorbeeld uit een database of een andere API.

Omdat het schema vastligt, kan een ontwikkelaar de API bevragen over zichzelf. Volgens Zonos houdt die introspectie de documentatie automatisch actueel: tools tonen welke velden er zijn en welke types ze hebben.

Hoe ziet een GraphQL-query eruit?

Een query lijkt op een uitgeklede versie van het antwoord dat je wilt krijgen. Je noemt het gegevenstype, bijvoorbeeld een klant met een bepaald nummer, en daaronder de velden die je wilt: naam en e-mailadres. Wil je ook de bestellingen, dan zet je die eronder, met daarbinnen weer de velden van een bestelling, zoals datum, bedrag en status.

Het antwoord heeft precies dezelfde vorm. Staat er geen telefoonnummer in de vraag, dan staat het ook niet in het antwoord. Daardoor is voor een ontwikkelaar direct te zien welke gegevens een scherm gebruikt.

Een mutation werkt vergelijkbaar. Je noemt de actie, zoals het aanmaken van een bestelling, geeft de benodigde gegevens mee en vraagt welke velden je terug wilt krijgen, bijvoorbeeld het nieuwe bestelnummer en de status.

Wat is het verschil tussen GraphQL en REST?

Testsigma en Moesif komen tot dezelfde conclusie: geen van beide is altijd beter. De keuze hangt af van de structuur van je gegevens, het belang van caching en hoeveel flexibiliteit de clients nodig hebben.

Wat is over-fetching en under-fetching?

Dit zijn de twee problemen die GraphQL vooral oplost.

• Over-fetching. Je krijgt meer gegevens dan je nodig hebt. Een REST-endpoint voor klanten geeft bijvoorbeeld alle velden terug, terwijl je alleen de naam wilt tonen. Dat kost bandbreedte en tijd, vooral op mobiele verbindingen.
• Under-fetching. Je krijgt te weinig in één keer en moet extra verzoeken doen. Eerst de klant, dan de bestellingen, dan de producten. Elk extra verzoek kost wachttijd.

Met GraphQL vraag je precies wat je nodig hebt, ook over meerdere gekoppelde gegevenstypen heen. Zonos geeft als voorbeeld dat ze met één GraphQL-aanroep gegevens ophalen waarvoor met REST drie aanroepen nodig waren.

Voordelen van GraphQL

• Precies de juiste gegevens. Minder dataverkeer en snellere schermen, vooral op mobiel.
• Minder verzoeken. Samenhangende gegevens in één keer ophalen.
• Sterk getypeerd schema. Fouten in de opbouw van een vraag vallen al vroeg op.
• Zelfbeschrijvend. Ontwikkelaars zien direct welke gegevens beschikbaar zijn.
• Doorontwikkelen zonder versies. Nieuwe velden toevoegen breekt bestaande clients niet.
• Meerdere bronnen achter één ingang. Volgens GFU kun je databases, andere API’s en zelfs bestanden combineren achter één GraphQL-interface.

Nadelen van GraphQL

• Caching is lastiger. Omdat elke query anders kan zijn, werkt standaard HTTP-caching minder goed.
• Meer complexiteit op de server. Schema, resolvers en beveiliging vragen meer opzetwerk dan een eenvoudige REST API.
• Zware queries. Een client kan een query sturen die heel veel gegevens tegelijk opvraagt. Zonder limieten kan dat de server belasten.
• Foutafhandeling wijkt af. Volgens Testsigma geeft GraphQL vaak een statuscode 200 terug, ook als er iets misgaat. De fout staat dan in het antwoord zelf, wat monitoring lastiger maakt.
• Leercurve. Teams moeten de querytaal, het schema en de bijbehorende tools leren.
• Bestandsuploads zijn niet standaard geregeld en vragen extra afspraken.

Wanneer kies je GraphQL en wanneer REST?

GraphQL past goed als:

• je veel gegevens hebt die onderling verbonden zijn;
• verschillende clients, zoals een website, een app en een dashboard, elk andere velden nodig hebben;
• je schermen wilt bouwen zonder steeds nieuwe endpoints te maken;
• realtime updates belangrijk zijn.

REST past goed als:

• de gegevensstructuur eenvoudig is;
• caching belangrijk is, bijvoorbeeld bij veel publieke lezers;
• andere partijen je API gebruiken en een bekende, eenvoudige standaard verwachten;
• het team REST al goed kent.

Voor veel zakelijke webapplicaties met één eigen voorkant is REST, of zelfs een directe koppeling tussen voorkant en backend binnen hetzelfde framework, eenvoudiger. GraphQL wordt interessant als er meerdere voorkanten zijn of als je een platform bouwt dat anderen gebruiken. Het kan ook andersom: een bestaand pakket biedt alleen een GraphQL API aan. Dan bepaalt die keuze van de leverancier hoe je koppeling wordt gebouwd, en is het goed om vooraf te weten welke gegevens en acties via die API beschikbaar zijn.

GraphQL in de praktijk

Bekende toepassingen van GraphQL zijn:

• Publieke API’s van platforms. GitHub en Shopify bieden GraphQL API’s aan waarmee ontwikkelaars precies de gegevens ophalen die ze nodig hebben.
• Mobiele apps. Minder dataverkeer en minder verzoeken zijn gunstig op trage verbindingen.
• Dashboards. Een scherm met gegevens uit veel bronnen haalt alles in één query op.
• Headless CMS’en. Veel contentsystemen bieden GraphQL om content in websites en apps te tonen.
• Koppelen van meerdere systemen. Eén GraphQL-laag kan gegevens uit verschillende databases en API’s samenvoegen.

Voor GraphQL zijn veel tools beschikbaar. GFU noemt Apollo en Relay als bekende bibliotheken, en ondersteuning in onder meer JavaScript, Python, Ruby en Java.

Overstappen van REST naar GraphQL

Een volledige overstap is zelden nodig. Veel organisaties kiezen voor een geleidelijke aanpak:

1. Begin met één gebruiker van de API, zoals de mobiele app of een nieuw dashboard.
2. Zet een GraphQL-laag voor bestaande REST API’s. De resolvers halen de gegevens dan op bij de bestaande endpoints.
3. Breid het schema stap voor stap uit met de gegevens die nieuwe schermen nodig hebben.
4. Laat REST bestaan voor koppelingen met andere partijen die daar al op werken.
5. Meet de belasting en voeg limieten en caching toe waar nodig.

Veelgemaakte fouten met GraphQL

• Het databaseschema één op één overnemen. Een goed GraphQL-schema volgt de behoeften van de schermen, niet de opbouw van de tabellen.
• Geen limieten op diepte en omvang van queries, waardoor één verzoek de server kan overbelasten.
• Rechten alleen op het hoogste niveau. Ook geneste velden moeten worden gecontroleerd.
• GraphQL kiezen omdat het modern is, terwijl een eenvoudige REST API volstaat.

Waar let je op bij een GraphQL API?

• Beveiliging per veld. Controleer niet alleen of iemand mag inloggen, maar ook welke velden en records hij mag zien.
• Limieten op queries. Beperk hoe diep en hoe groot een query mag zijn.
• Monitoring. Omdat fouten niet altijd in de statuscode zitten, moet je het antwoord zelf controleren.
• Documentatie van het schema. Geef velden duidelijke namen en beschrijvingen.

Wat betekent dit voor jouw project?

De keuze tussen GraphQL en REST is een technische afweging die volgt uit het proces. Wat komt binnen, wie moet ermee verder en welke informatie heeft die persoon nodig? Als duidelijk is welke schermen en koppelingen er zijn, wordt ook duidelijk welke vorm van API past.

Bij een nieuw idee onderzoek ik eerst of een bestaand pakket, een koppeling of maatwerk het beste past. Bij een koppeling kijk ik welke API een pakket aanbiedt, REST of GraphQL, en wat die API wel en niet kan. In de betaalde blauwdruk leg ik die afhankelijkheden vast, zodat de techniek de eerste versie ondersteunt en niet ingewikkelder maakt dan nodig.

Vraag? Moet jouw applicatie gegevens uit meerdere systemen samenbrengen? Stuur me welke systemen het zijn en wie de gegevens nodig heeft. Dan bepalen we samen de logische eerste stap. Lees ook wat er komt kijken bij een webapplicatie bouwen.

Veelgestelde vragen over GraphQL

Wat is GraphQL in simpele woorden?

GraphQL is een manier om gegevens op te vragen bij een API, waarbij je zelf precies aangeeft welke velden je wilt. Alle vragen gaan naar één adres, en je krijgt een antwoord met precies de gevraagde structuur terug.

Wat is het verschil tussen GraphQL en REST?

REST werkt met een apart adres per soort gegeven, en de server bepaalt wat je terugkrijgt. GraphQL werkt met één adres, en de client bepaalt welke velden hij ontvangt. REST is eenvoudiger en makkelijker te cachen, GraphQL flexibeler bij samenhangende gegevens.

Is GraphQL een database?

Nee. GraphQL is een querytaal voor API’s, geen database. Achter een GraphQL API kunnen één of meerdere databases en andere API’s zitten, die via resolvers de gevraagde gegevens leveren.

Verwante termen

API · API-koppeling · Database · Software-architectuur · Webapplicatie