29 juni 2020 2 minuten

GraphQL: de query-taal voor API’s

#craftcms #graphql #craft 4 #api
Niels website

Maak kennis met GraphQL en de mogelijkheden die Craft CMS hieromtrent aanbiedt.

Wat is GraphQL?

GraphQL (Graph Query Language) is een open-source query-taal voor API’s met een runtime omgeving die intern werd ontwikkeld door Facebook. Net als REST (REpresentational State Transfer) kan je hiermee binnen een front-end applicatie verzoeken versturen naar een back-end applicatie.

Een transferverzoek bij GraphQL bestaat uit queries, waarbij gespecificeerd wordt wat men van de database nodig heeft. Om de gewenste data op te halen doen we beroep op de runtime omgeving van GraphQL. Deze draait mee in de back-end applicatie en zet de queries om naar functies. Deze functies gaan op hun beurt op zoek naar data in de database.

Graphql

Wat zijn de voordelen t.o.v. een RESTful webservice?

Endpoints

Het grootste verschil tussen GraphQL en REST zijn het aantal endpoints. Bij REST heb je meerdere endpoints, waarbij iedere endpoint een vaste data structuur teruggeeft. Al deze endpoints moeten tijdens het ontwikkelen van een applicatie aangemaakt worden.

GraphQL heeft slechts één endpoint, waarbij we de exacte data terugkrijgen.

Under- en overfetching

Stel dat we een pagina hebben binnen een applicatie waarbij we de volgende data nodig hebben: bestellingen, producten en klanten. Om deze zaken op ons scherm te zien moeten we bij RESTful webservices 3 keer een transferverzoek doen naar de backend. Je krijg niet alle data in één keer terug, omdat je meerdere calls moet doen. Dit is een voorbeeld van underfetching.

Omgekeerd kan het ook. Vaak bevatten endpoints overtollige data. Als we de profielpagina van een gebruiker willen uitprinten, kan het gebeuren dat we al zijn blogposts terugkrijgen omdat we diezelfde endpoint gebruiken voor een pagina waar we zijn blogposts uitlezen. Dit zijn zaken die je wilt vermijden wanneer een gebruiker transferverzoeken doet via een mobiel netwerk, omdat hij zo meer data verbruikt dan nodig. Dit wordt overfetching genoemd.

Bij GraphQL komen deze zaken niet voor, omdat we exact hetgeen gaan opvragen die we nodig hebben per pagina.

GraphQL in Craft 3

IDE

Sinds Craft 3 zien wij een integratie van GraphQL. CraftQL is een plugin met een IDE (Integrated Development Environment) waarbij je in de backend queries kan opbouwen. Pixel and Tonic zag deze web development trend en ging hiermee aan de slag. Sinds Craft 3.3 biedt het CMS, na het verwerven van een pro licentie, GraphQL aan. De IDE lijkt sterk op die van de plugin CraftQL en is uiterst gebruiksvriendelijk.

Schema

Een GraphQL schema definieert welke queries je allemaal kan sturen naar je endpoint. In dit schema bepaal je alle entries, assets, globals en users die de gebruiker mag opvragen. Standaard heeft GraphQL in Craft een lege public schema.

Schermafbeelding 2020 06 30 om 09 59 39

Tokens

Er zijn scenario’s waarbij je liever je schema private maakt. Dit kan je doen door een token te genereren en die te koppelen aan een schema. Van zodra dit is ingesteld kan je het schema enkel aanspreken als je de token meestuurt tijdens het verzoek.

Queries

GraphQL heeft een eigen syntax. Hoe je met deze syntax moet omgaan als developer kan je ontdekken in de documentatie van Craft CMS. In de verkenner van GraphQL IDE kan je queries opbouwen aan de hand van de Documentation Explorer. Deze feature biedt je de mogelijkheid om in no-time de syntax onder de knie te krijgen. Na het versturen van je query krijgen je een JSON object terug die je kan verwerken op de pagina.

Schermafbeelding 2020 06 30 om 09 59 16

Mutations

Op dit moment is de GraphQL webservice van Craft enkel read-only. In Craft 4 zal het mogelijk zijn om mutations uit te voeren. Hiermee kunnen we data uit de database aanpassen of nieuwe data toevoegen.

Conclusie

Craft biedt met GraphQL een out-of-the-box auto generated webservice aan die ervoor zorgt dat we geen tijd verliezen met het maken van endpoints. Door de flexibele en krachtige querytaal en de gebruiksvriendelijke IDE kan je meteen van start in de front-end. Het is een prima alternatief voor RESTful webservices die op de koop toe over- en underfetching omzeilt.

Wil je meer informatie over GraphQL of over Craft CMS in het algemeen?

Aarzel niet om ons te contacteren!

Stay updated!
Nieuwsbrief

Schrijf je in voor onze nieuwsbrief

Wil je op de hoogte blijven van de laatste digitale trends, tips & tricks, interessante events en seminaries? Schrijf je dan in voor onze nieuwsbrief.

Schrijf mij in!