GraphQL on tehokas rajapinta, kun tietää, mitä on tekemässä. Se vaatii kuitenkin täysin erilaisen tavan ajatella datan rakennetta sekä siirtoa. Oman kokemukseni mukaan suurin haaste onkin se, että GraphQL:n käyttö opitaan väärin. Omaksuttavaa on enemmän kuin perinteisissä REST- ja SOAP-rajapinnoissa, mutta oikein käytettynä se on monessa tilanteessa ylivoimainen valinta.
GraphQL on oiva valinta modernin web-projektin rajapinnaksi. Nimensä mukaisesti kyseessä on graafeja tukeva kyselykieli, jota hyödyntäen asiakassovellus ja palvelin keskustelevat keskenään. Toisin kuin useimmissa muissa rajapintojen toteutustavoissa, GraphQL:ssä rajapintakyselyn tekevä taho määrittää, mitä tietoja se haluaa palvelimelta takaisin lähetettävään vastaussanomaan.
Mitä tarkoitetaan, kun puhutaan GraphQL:stä?
Puhuttaessa GraphQL:stä, on olennaista ymmärtää, missä kontekstissa termiä käytetään.
-
GraphQL-spesifikaatio: GraphQL:n ytimessä on GraphQL-spesifikaatio, jonka tehtävänä on määritellä puitteet tämän spesifikaation täyttäville toteutuksille. Spesifikaatio määrittelee mm. miten kyselyitä tehdään ja miten palvelun kuuluu vastata eri tilanteissa.
-
GraphQL-rajapintakirjastot eli spesifikaation toteuttavat kirjastot niin frontendiin kuin backendiin. Eri kirjastototeutuksilla on omat vahvuutensa, heikkoutensa, ja ne soveltuvat eri vaatimuksiin.
-
GraphQL-ekosysteemi eli miten rakennetaan toimiva kokonaisuus GraphQL-rajapintojen ympärille. Näitä ovat mm. kirjastot, kuten dataloadaus, jotka ratkaisevat tiettyjä GraphQL:n tuomia arkkitehtuurisia haasteita.
Mihin GraphQL sopii ja mihin ei?
GraphQL on parhaimmillaan silloin, kun datamalli on monimutkainen tai dataa yhdistellään useista eri taustajärjestelmistä. Se on ihanteellinen, jos samaa rajapintaa käyttää useampi eri client-sovellus, sillä rajapintaa ei täydy erikseen räätälöidä jokaisen tarpeisiin sopivaksi, vaan GraphQL-asiakasohjelma (client) voi pyytää yhdellä kyselyllä täsmälleen tarvitsemansa tiedot. Tämä estää tehokkaasti REST-rajapinnoille tyypillisen yli- ja alikyselyn (over- and under-fetching) ja säästää verkkoliikennettä. Lisäksi GraphQL:n sisäänrakennetut Subscription-kyselyt tekevät siitä oivan valinnan reaaliaikaista datapäivitystä vaativiin ratkaisuihin.
GraphQL ei kuitenkaan ole aina “oikea” valinta. Suoraviivaisiin CRUD-sovelluksiin perinteisempi REST-arkkitehtuuri on usein kevyempi ja nopeampi toteuttaa.
Mitä huomioida GraphQL:n käyttöönotossa?
Käyttöönotossa on kriittistä huomioida GraphQL:n luomat vaatimukset taustajärjestelmälle. Verrattuna perinteisiin SOAP-, REST-, JSON-rajapintoihin GraphQL-käyttäjän lähettämän hakupyynnön datan sisältö määrittelee, mitä rajapinta tekee ja palauttaa. Perinteisissä rajapinnoissa voidaan toki parametrisoida hakuja, mutta yleensä näillä vaikutetaan vain paluusanoman sisältöön, ei niinkään sen muotoon.
Olennaista asiassa on ymmärtää, että olemassa olevaa REST-rajapintaa ei kannata korvata suoraan GraphQL:llä. Tuloksena on usein vain iso pettymys ja huonosti toimiva rajapinta.
GraphQL:n jyrkkä oppimiskäyrä
Ne muutamat kerrat, kun olen projekteissa kuullut negatiivista palautetta GraphQL:stä teknologiana, tekijät eivät ole ymmärtäneet, mitä he ovat tekemässä. Paradigman muutos on vaikeaa ja väärät oletukset kohtalokkaita. Kuten minkä tahansa työkalun kanssa, ensin pitää ymmärtää, mihin se sopii ja miten sitä käytetään. Vasta sitten työnjälki ja tulokset ovat hyviä.
GraphQL:ssä on valtava määrä omaksuttavaa tietoa. Se on huomattavasti kompleksisempi kokonaisuus ymmärtää kuin perinteiset rajapinnat ja oppimiskäyrä on jyrkkä. Olen opettanut usealle ohjelmistokehittäjälle GraphQL:ää ja törmännyt aina haasteeseen, että opetettavan tiedon määrä on niin valtava, ettei sitä pysty mitenkään omaksumaan kerralla.
Omaksuminen vaatii myös käytännön kokemusta. Vaikka kuinka olen varoittanut tietyistä komplekseista “vaaroista”, lopputulos on aina se, että oppi menee lopullisesti perille vasta kun niihin kerran langetaan.
Vain tekemällä oppii
GraphQL:stä löytyy monia rajapintakirjastoja ja näille tutoriaaleja Internet pullollaan. Tämän lisäksi AI-työkalut taitavat hyvin GraphQL:ää, joten omia tarpeita vastaavan hiekkalaatikon pystyttäminen ei ole vaikeaa. Kun hiekkalaatikko on pystyssä, paras tapa oppia on yrittää ja erehtyä, sillä käytännön kokemusta saa vain tekemällä.
Käytetyllä rajapintakirjastolla ei ole suurtakaan merkitystä. Kaikissa niissä on omat hyvät ja huonot puolensa, mutta kaikilla pääsee hyvin alkuun. Mitä tulee oppimateriaaleihin, niin ehkä vähän nurinkurisesti suosittelisin välttämään GraphQL:n spesifikaatiota. Spesifikaation resoluutio on liian tarkka eikä se ole tarpeeksi käytännönläheinen opiskelumateriaali. Oman näkemykseni mukaan se onkin ensisijaisesti tarkoitettu GraphQL-rajapintakirjastojen kehittäjille.
Syvempi tieto, paremmat päätökset
Kun perusteet ovat hallussa, aiheeseen voi syventyä kunnolla. Verkosta löytyviin GraphQL-neuvoihin ei kannata kuitenkaan aina luottaa sokeasti. Olen törmännyt useamman kerran suosituksiin toimia tavalla, joka mm. on GraphQL:n spesifikaation vastaista. Tarjotut vastaukset ovat usein hyvin yksioikoisia, eivätkä vastaa todellisuuden kompleksisuutta.
Valveutunut koodari osaa myös miettiä, mikä kyselyissä voi mennä vikaan ja miten siitä ilmoitetaan käyttäjälle. Tässä GraphQL tarjoaa mahdollisuuksia, joita ei valitettavasti usein ymmärretä käyttää.
Esimerkiksi käyttämällä union- ja interface-tyyppejä erilaiset odotetut liiketoimintatilat ja vaihtoehtoiset lopputulokset voidaan rakentaa osaksi itse rajapinnan kuvausta eli skeemaa, jolloin asiakassovellus tietää aina tarkasti, mitä tilanteita sen on osattava käsitellä.
Kun GraphQL:n vaatimuksia ja mahdollisuuksia alkaa ymmärtää syvemmin, rajapinnan suunnittelu alkaa sujua. Tämän jälkeen on mahdollista tehdä valistuneita arkkitehtuurisia päätöksiä esim. siitä, mitä GraphQL-teknologioita kannattaa käyttää omassa projektissaan.
Vaikka tekoäly on yhä tiiviimpi osa ohjelmistokehitystä, tätä arkkitehtuurista pohjatyötä ja syvää ymmärrystä se ei voi korvata. AI ei osaa automaattisesti ajatella skeemaa holistisesti tai huomioida suorituskykyä. Se ehdottaa helposti naiiveja rakenteita ja toistaa verkosta poimimiaan huonoja käytäntöjä – esimerkiksi virheiden käsittelyssä. Tekoäly kyllä auttaa valtavasti ja tekee hyvää jälkeä, kunhan sille osaa tarpeeksi tarkasti kertoa kriteerit. Eli omaa ymmärrystä tarvitaan, ja GraphQL-rajapinta-arkkitehdin roolia ei kannata ulkoistaa AI:lle… ainakaan vielä.
Aloita puhtaalta pöydältä
Itse olen oppinut GraphQL:n ns. “kantapään kautta” ja suurimmat ongelmat ovat tulleet, kun olen olettanut, että asiat toimivat kuten perinteisissä rajapinnoissa. GraphQL:n oppiminen kannattaa aloittaa avoimin mielin ja pyrkiä välttämään olettamuksia. On selvää, että sen käyttöönotossa on oma oppimiskäyränsä, sillä sen ympärillä olevat ratkaisut vaativat erilaista lähestymistapaa verrattuna perinteisiin RESTin kaltaisiin APEihin.
Aloita siis mieluiten puhtaalta pöydältä ja älä aloita matkaasi sillä, että yrität korvata toimivan REST-rajapinnan GraphQL:llä, sillä tuloksena on joko huonommin toimiva rajapinta tai paljon enemmän työtä ja opeteltavaa, mihin olet valmistautunut. Onnistunut muutos kun vaatii muutakin kuin vain API-kerrokseen koskemista.
Suosittelen GraphQL:n kokeilemista. Sen ymmärtäminen on yleissivistävä kokemus, joka opettaa katsomaan rajapintaongelmia uudessa valossa – silloinkin, vaikkei sitä jatkossa edes käyttäisi.
