API NL Meetup: Hypermedia & GraphQL

Waarom leggen we de verantwoordelijkheid van wat de API moet returnen niet bij de frontend zelf? Tijdens de API NL meetup leerden we onder andere over GraphQL.

Samen met Ely en Jorik bezocht ik de tweede meetup van API NL. Het onderwerp was Hypermedia en GraphQL en werd gehost door Blendle in hun kantoor in Utrecht. 
Erik Terpstra gaf het eerste praatje over hoe HyperMedia API gebruikt wordt binnen Blendle en het laatste praatje was van Joost Cassee over Hypermedia and API evolution. Zeer interessante praatjes en het is altijd leuk om in de keuken van een ander product te kijken.

Wij kwamen vooral voor het tweede praatje, over GraphQL.

REST, views of ...?

Stel, je hebt een pagina met een contactlijst die je moet ophalen bij een REST api, daarnaast wil je ook direct het geselecteerde contact ophalen. In de UI kunnen nog elementen zitten die niet voor elke gebruikersrol zichtbaar zijn, dus hebben we ook nog de ingelogde gebruiker nodig. Dit zijn drie makkelijke calls en het is geen uitzondering dat een pagina veel meer nodig heeft.

Een oplossing hiervoor kan zijn om met views te werken. De API heeft een speciale endpoint voor het scherm dat jij wilt laten zien en de data die daar op te zien moet zijn in 1 view teruggeeft. Je kan dan een heel scherm direct weergeven met maar 1 API call. Dit wordt echter een probleem als je meerdere soorten frontends hebt (iOS, Android en web bijvoorbeeld) en er een scherm in de iOS app helemaal omgegooid wordt, maar nog wel de oude moet supporten. Je hebt dan opeens een aantal verschillende versies voor 1 scherm dat bij elke wijziging in de frontend blijft groeien en dat is een hel om te onderhouden.

Waarom leggen we de verantwoordelijkheid van wat de API moet returnen niet bij de frontend zelf? En dat is waar het 2e praatje over ging: GraphQL gegeven door Dionysis Pantazopoulos & Robert Ignat van Jexia

GraphQL

GraphQL is een query language en runtime ontwikkeld door Facebook en is intern in gebruik sinds 2012 voor hun mobiele apps en site.
Kort gezegd kun je hiermee queries uitvoeren op je API in plaats van simpele GET requests om een kant-en-klaar object op te halen. Je stuurt een request naar je GraphQL endpoint in een formaat zoals je het request gevuld zou willen hebben, bijvoorbeeld:

Hierboven vragen we bij de server alle bedrijven waarvan Elon Musk de CEO is, en daarvan alleen de naam.

Als dit een bestaande API zou zijn zou dit de response kunnen zijn:

Of, om de kracht te laten zien van GraphQL, een query waarbij je connecties van het model joined en daarmee meerdere queries in 1 keer laat uitvoeren:

Wat resulteert in de response:

Zoals je ziet is de GraphQL query zelf ook hiërarchisch opgebouwd en is de data die je terugkrijgt meer een ‘ingevulde’ query.

GraphQL server

Natuurlijk werkt dit niet magisch en moet je hiervoor wel de GraphQL server implementeren. GraphQL zelf is alleen een specificatie, maar er zijn al een aantal implementaties te vinden in bijvoorbeeld Javascript of C#.
Om te beginnen moet je een type schema definiëren van je API. Dit betekent dat je moet aangeven welke fields en models de client kan queryen bij je GraphQL server.

Een kort voorbeeld uit het schema van de Star Wars GraphQL:

En zie hier het hele schema.

Het is dus niet zo dat je GraphQL in je project kan droppen en klaar, maar ik kan me zo voorstellen dat je in de toekomst misschien je graph kan genereren, de informatie is er tenslotte al. Er is bijvoorbeeld wel een project om een GraphQL te genereren vanuit je SQL database, maar dat is meer opgezet om je op gang te helpen met je eerste graph.

IDE

Bij GraphQL zit ook de GraphiQL, een IDE die je aan je endpoint kan koppelen en gemakkelijk je queries kan uitwerken en testen.

Hierin kunnen de frontend developers hun queries samenstellen alleen met de data die zij nodig hebben, in plaats van dat ze moeten puzzelen met verschillende API calls of weer een nieuw endpoint moeten aanvragen bij de backend.
Omdat het schema helemaal is vastgelegd en type-safe, kan je alles typen met code completion.

Mutaties

GraphQL is niet alleen bruikbaar om data op te vragen, maar kan ook mutaties aan de backend doorgeven. GraphQL heeft hier Mutations voor. Mutations verschillen niet veel van de Queries die je in je schema definieert, met als enige verschil dat ze side-effects hebben. Daarnaast worden queries in willekeurige volgorde uitgevoerd, maar mutations serieel. Het resultaat in de volgende GraphQL Mutations query is dan ook 2:

Bleeding edge

Zoals Facebook zelf al aangeeft is de specificatie nog aan wijzigingen onderhevig en de Javascript library een "Technical preview of the Javascript reference implementation", maar tot zo ver ziet het er zeer interessant uit. Vooral voor API heavy apps waarvan de API helemaal REST is opgezet kan het zeker een performance boost en flexibiliteit opleveren. Het zal vast niet de oplossing zijn voor elke API, maar we gaan het hier zeker een keer als een experiment naast de huidige API in een project zetten.

Will report back!

[Corné is ontwikkelaar bij Infi]

Gezocht: ondernemende nerds!

› Wil jij je hersens bij ons laten kraken?

Wil je iets waarmaken met Infi?

Wil jij een eigen webapplicatie of mobiele app waarmee jij het bij anderen maakt?

Waargemaakt door de nerds van Infi.
Nerds met liefde voor softwareontwikkeling en die kunnen communiceren. En heel belangrijk: wat we doen, doen we met veel lol!

Wij willen het fixen. Laat jij van je horen?

Voor wie heb je een vraag?