GraphQL — wat het is, querytaal en toepassing in mobiele projecten

Wat is GraphQL?

GraphQL — is een specificatie en runtime-omgeving voor API die de client volledige controle geeft over de ontvangen gegevens. Ontwikkeld door Facebook-ingenieurs om de problemen van de mobiele News Feed-app op te lossen, werd de specificatie in 2015 als open standaard gepubliceerd. Sinds 2018 valt GraphQL onder het beheer van de GraphQL Foundation met steun van de Linux Foundation en bedrijven zoals Apollo, AWS, GitHub, SAP en anderen.

In tegenstelling tot REST, waar elke endpoint een vaste gegevensstructuur retourneert, gebruikt GraphQL een enkele endpoint die een querytekenreeks ontvangt. De client beschrijft in de query welke velden nodig zijn en de server retourneert precies die. Bijvoorbeeld de query { user(id: „1”) { name email } } retourneert alleen de name en email van de gebruiker, zonder overbodige velden zoals address, phone of createdAt die in REST zouden moeten worden opgehaald.

GraphQL is niet gebonden aan een specifieke database of taal. De specificatie definieert alleen het formaat van query’s en antwoorden. Er zijn serverimplementaties in Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) en andere talen. Clientbibliotheken zijn beschikbaar voor alle belangrijke platformen, waaronder Apollo Client voor iOS, Android en het web.

Hoe werkt GraphQL

De architectuur van GraphQL bestaat uit drie belangrijke componenten: het schema (Schema), resolvers (Resolvers) en de uitvoeringsengine (GraphQL Engine). Het schema bepaalt welke gegevenstypen beschikbaar zijn, welke query’s kunnen worden uitgevoerd en welke argumenten ze accepteren. Resolvers zijn functies op de server die gegevens retourneren voor elk veld van het schema. De uitvoeringsengine ontvangt de inkomende query, valideert deze tegen het schema, roept de juiste resolvers aan en stelt het antwoord samen.

Het verwerkingsproces van een query ziet er als volgt uit:

• De client stuurt een POST-verzoek naar /graphql met JSON-body { „query”: „...” }
• De server parseert de query, bouwt een AST (Abstract Syntax Tree) en valideert deze tegen het schema
• De engine doorloopt de AST, roept resolvers aan voor elk veld en verzamelt gegevens
• Het antwoord wordt geretourneerd in JSON-formaat, precies overeenkomend met de querystructuur

Het belangrijkste voordeel van de GraphQL-architectuur is resolutie op veldniveau. In REST krijgt de ontwikkelaar ofwel alle velden van de resource (mogelijk met overbodige gegevens), of grijpt hij naar uitbreidingen zoals ?fields=name,email. In GraphQL is dergelijke filtering ingebouwd in de taal: elke query specificeert expliciet welke velden nodig zijn en de server retourneert precies die. Dit is vooral belangrijk voor mobiele applicaties, waar de hoeveelheid overgedragen gegevens direct van invloed is op de laadsnelheid en het dataverbruik.

Query, Mutation en Subscription

GraphQL definieert drie soorten bewerkingen, die elk overeenkomen met een specifiek interactiescenario. Query — voor het lezen van gegevens, analoog aan GET in REST. Mutation — voor het wijzigen van gegevens (creëren, updaten, verwijderen), analoog aan POST/PUT/DELETE. Subscription — voor real-time updates via WebSocket, wat geen directe analogie heeft in klassieke REST (vereist extra oplossingen zoals WebSocket of Server-Sent Events).

De basissyntaxis van query’s is intuïtief:

// Eenvoudige query met argument
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation met terugkeer van gewijzigde gegevens
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — luistert naar real-time updates
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query wordt parallel uitgevoerd — alle velden op hetzelfde niveau worden tegelijkertijd geladen. Dit maakt het mogelijk om gerelateerde gegevens (gebruiker en zijn berichten) te laden met één query zonder meerdere round-trips. Mutation wordt sequentieel uitgevoerd — mutaties in één query worden na elkaar uitgevoerd in de volgorde van declaratie. Subscription brengt een permanente verbinding tot stand via WebSocket, waarlangs de server gegevens stuurt wanneer een gebeurtenis plaatsvindt.

Bewerkingen kunnen variabelen accepteren om gegevens van de query te scheiden, directives (@include, @skip) voor voorwaardelijke opname van velden en fragmenten voor hergebruik van veldverzamelingen. Deze mogelijkheden maken GraphQL-query’s flexibel en herbruikbaar, wat vooral belangrijk is in grote projecten met meerdere schermen en componenten.

GraphQL schema en typesysteem

Aan de basis van GraphQL ligt het typesysteem, dat alle mogelijke gegevens en bewerkingen van de API beschrijft. Het schema (Schema) is een beschrijving van de typen die de server kan retourneren en de query’s die hij accepteert. Het schema wordt geschreven in de Schema Definition Language (SDL) en dient als contract tussen de client en de server. De client kan het schema verkrijgen via introspectie — een speciale __schema-query die een volledige beschrijving van de API retourneert.

Voorbeeld van een schema voor een blog:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Het uitroepteken (!) betekent een non-null veld — het zal gegarandeerd aanwezig zijn in het antwoord. Vierkante haakjes [ ] geven een lijst aan. GraphQL ondersteunt scalaire typen (Int, Float, String, Boolean, ID), objecttypen, enum, union, interface en input-typen (voor mutatie-argumenten). Strikte typering documenteert de API zelf en stelt clienttools in staat code te genereren: TypeScript-typen, Kotlin-data-klassen, Swift-structuren.

Introspectie — een unieke mogelijkheid van GraphQL die niet bestaat in REST. De client kan een query naar het schema sturen en een volledige beschrijving van alle typen, velden, argumenten en directives ontvangen. Dit vormt de basis van tools zoals GraphiQL en Apollo Studio, die automatisch documentatie en autocomplete voor ontwikkelaars genereren. Introspectie maakt het ook mogelijk om geautomatiseerde tests te schrijven die de overeenstemming van het schema met de verwachte structuur controleren.

GraphQL versus REST

De keuze tussen GraphQL en REST is een van de belangrijkste architecturale vragen bij het ontwerpen van API’s. Beide benaderingen hebben hun sterke en zwakke punten, en de keuze hangt af van de specifieke vereisten van het project. REST wint in eenvoud en universaliteit, GraphQL in flexibiliteit en query-efficiëntie. Laten we de vergelijkingstabel bekijken.

Het grootste nadeel van GraphQL is de complexiteit van caching. In REST werkt HTTP-caching op URL-niveau: één verzoek naar /api/users/42 retourneert altijd dezelfde structuur en het antwoord kan per URL worden gecached. In GraphQL gaan alle verzoeken naar één endpoint, de structuur van het antwoord hangt af van de verzoekbody. Om dit probleem op te lossen gebruikt Apollo Client een genormaliseerde cache aan de clientzijde die antwoorden opsplitst in afzonderlijke entiteiten op basis van id en ze automatisch bijwerkt bij het ontvangen van nieuwe gegevens.

Een ander belangrijk aspect is het N+1-probleem. Bij het opvragen van geneste gegevens (bijvoorbeeld berichten van een gebruiker en reacties op elk bericht) kan GraphQL een afzonderlijke SQL-query uitvoeren voor elk element van de lijst. Dit wordt opgelost met DataLoader — een tool voor het batchen en cachen van databasequery’s die afzonderlijke query’s groepeert in één batchquery. In REST is dit probleem minder uitgesproken omdat de ontwikkelaar de structuur van het antwoord op de server controleert.

Voorbeelden van GraphQL-query’s

Laten we praktische voorbeelden bekijken van het gebruik van GraphQL in een mobiele applicatie in Kotlin met Apollo Client. De voorbeelden demonstreren typische scenario’s: het laden van gegevens voor een profielscherm (query), het maken van een nieuw bericht (mutation) en het abonneren op nieuwe reacties (subscription). Elk voorbeeld bevat zowel de GraphQL-query als de code aan de clientzijde.

Query: profiel met berichten laden

Eén GraphQL-query laadt de gebruiker, zijn laatste berichten en het totale aantal volgers. In REST zouden hiervoor minimaal 2-3 verzoeken nodig zijn: /users/42, /users/42/posts, /users/42/stats. GraphQL combineert ze in één round-trip, waardoor de laadtijd van het scherm op trage verbindingen wordt verkort.

// GraphQL-query (in .graphql-bestand)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Aanroep aan clientzijde (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: een nieuw bericht maken

De mutatie creëert niet alleen de resource, maar retourneert ook de actuele gegevens voor het bijwerken van de UI. Het veld __typename wordt door Apollo Client gebruikt voor normalisatie van de cache — de client werkt automatisch het Post-record in de cache bij bij een succesvol mutatie-antwoord.

// GraphQL-mutatie
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Mutatie-aanroep met input-type
val input = CreatePostInput(
    title = "Nieuw bericht over GraphQL",
    content = "GraphQL vereenvoudigt het werken met API’s..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Een belangrijk voordeel van GraphQL ten opzichte van REST in de context van mobiele ontwikkeling is automatische codegeneratie. Apollo Client voor Kotlin (Apollo GraphQL) genereert typeveilige klassen uit .graphql-bestanden tijdens de buildfase. Als de server het schema wijzigt, wordt het project niet gebouwd totdat de query’s zijn bijgewerkt. Dit voorkomt runtime-fouten die kenmerkend zijn voor REST, waar een wijziging in de antwoordstructuur tijdens de ontwikkeling onopgemerkt kan blijven.

Ecosysteem: Apollo, Relay en tools

Het GraphQL-ecosysteem omvat verschillende belangrijke bibliotheken en tools die ontwikkeling en exploitatie vereenvoudigen. Apollo Client — de populairste clientbibliotheek, die React, iOS, Android en Kotlin Multiplatform ondersteunt. Relay van Facebook — een alternatief voor React-applicaties met een unieke benadering van gegevensbeheer en caching. De keuze tussen Apollo en Relay hangt af van het platform en de prestatie-eisen.

Aan de serverzijde leiden Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) en graphql-ruby. Voor het ontwikkelen van het schema en het testen van query’s wordt GraphiQL gebruikt — een interactieve IDE ingebouwd in de browser. Apollo Studio biedt prestaties, query-tracering en schemabeheer voor de productieomgeving. Afzonderlijk moet GraphQL Code Generator worden genoemd — een tool die TypeScript-, Kotlin-, Swift- en Dart-typen genereert uit SDL-schema’s.

Voor mobiele ontwikkeling is Apollo Kotlin (Apollo GraphQL) bijzonder interessant — een bibliotheek volledig geschreven in Kotlin met ondersteuning voor coroutines, Flow en Multiplatform. Hiermee kunnen dezelfde GraphQL-query’s worden gebruikt voor Android en iOS in Kotlin Multiplatform-projecten. Apollo Kotlin normaliseert de cache, ondersteunt fouten op veldniveau (partial errors) en genereert automatisch gegevensmodellen uit .graphql-bestanden. Dit maakt GraphQL de voorkeurskeuze voor grote mobiele projecten waar ontwikkelingssnelheid en typeveiligheid belangrijk zijn.