Gå til hovedinnhold

Pilotere GraphQL som standard utviklingsteknologi for APIer

Vi gjennomfører en pilot av GraphQL med den hensikt å avdekke om dette er en egnet standard for tilgjengeliggjøring av informasjon og funksjonalitet fra FS til Sikt, sektoren og privat næring.

Kontekst og problembeskrivelse​

Målarkitekturen til FS sier:

FS må etableres som en plattform som tilrettelegger for digital transformasjon. Plattformen skal gjøre det mulig for utviklere å lage applikasjoner og integrasjoner som utnytter FS-data og FS-prosesser for å løse behovene til sektoren og næringslivet. Den må bygges på en måte som gjør at kontinuerlig utvikling kan utføres på en økonomisk bærekraftig og forutsigbar måte.

Målarkitekturen dikterer videre at de programmerbare grensesnittene (APIene) i FS-plattformen skal være den eneste måten man kan aksessere data og forretningslogikk for FS, og at man dermed må gå over til å utvikle etter API-først prinsippet.

Sektoren erfarer at dagens APIer er vanskelige å forstå og bruke siden de krever inngående forståelse av FS-datamodellen. Det er i tillegg vanskelig å få gjennomslag for utvidelser og forbedringer. Funksjonalitet som blir lovet tar ofte lang tid å etablere og det er ikke uvanlig at endringer innfører feil eller annen ustabilitet.

Internt opplever vi at APIene våre er vanskelige å vedlikeholde og at det tar for lang tid å tilgjengeliggjøre data og funksjonalitet på en god måte. Listen med forespørsler og behov fra sektoren vokser dermed langt raskere enn vi klarer å håndtere.

Disse problemene mener vi dels skyldes en kombinatorisk eksplosjon av behov, informasjonsmodeller og tekniske løsninger. REST-APIer er svært godt egnet til å tilgjengeliggjøre funksjonalitet for små systemer og/eller begrensede domener. For større systemer som FS, hvor man har mange forskjellige datasett som gir merverdi i lys av hverandre, så ser vi at REST-APIer mangler standardiserte måter å løse endel viktig funksjonalitet.

Når vi nå skal legge vesentlig større vekt på API-utvikling så er det viktig at vi finner en retning for API-utvikling som adresserer disse problemene på en god måte.

Motivasjon​

Unit sitter på en enorm verdi i form av en rik og konsistent datamodell som understøtter hele UH-sektorens behov for studieadministrative tjenester. Etterspørselen etter å kunne utnytte data og funksjoner i FS er voksende og relevansen for et felles studieadminstrativt system er større enn noen gang.

Vi ønsker å svare ut retningen som settes av målarkitekturen til FS og ønskene til sektoren. Dette mener vi skal være mulig å gjøre på en vesentlig mer effektiv og vedlikeholdbar måte enn tidligere, dersom vi tar i bruk verktøy som spiller godt sammen med styrkene som ligger i FS sin interne arkitektur.

Hovedproblemene vi ønsker å løse kan grovt deles opp i følgende:

  1. Hvordan skal FS-plattformens informasjonsinnhold og funksjon defineres, publiseres og forvaltes
  2. Hvordan kan vi bygge APIer slik at utvidelser samspiller med eksisterende funksjonalitet og dermed gir eksponensiell merverdi
  3. Hvordan skal data og informasjonsmodell fra FS benyttes
  4. Hvordan kan 1, 2 og 3 knyttes sammen på en effektiv og fleksibel måte

Alternativer​

Vurdert:

Ikke vurdert:

Avgjørelse​

Vi anbefaler at man gjennomfører en pilot av GraphQL med den hensikt å avdekke om dette er en egnet standard for tilgjengeliggjøring av informasjon og funksjonalitet fra FS til Unit selv, sektoren og til privat næring.

Positive konsekvenser​

Spørrespråket i GraphQL gjør det mulig for konsumenter å hente all informasjon som trengs i en forespørsel. Dette gjør det langt enklere for konsumenten å bygge integrasjoner og applikasjoner, som følge av at behovet for å sammenstille data på klientsiden reduseres vesentlig.

Videre gjør standarden det mulig å legge til informasjon og funksjonalitet på en måte som ikke påvirker eksisterende brukere, samtidig som utvidelsene gir eksponensiell merverdi.

Det finnes i dag mange modne implementasjoner av GraphQL-standarden. De fleste av disse utvikles som åpen kildekode og medfører dermed ikke lisenskostnader. Vi har testet noen av disse verktøyene og opplever at de gjør det overraskende enkelt å bygge APIer som følger standarden.

Det finnes i tillegg gode verktøy som gjør det enkelt å utforske og bruke GraphQL-APIer. Igjen er disse i stor grad åpen kildekode, noe som lar oss bygge verktøyene inn i FS-plattformen. Dette er heldig siden vi ønsker å etablere utviklingen av FS-plattformen som åpen kildekode.

Brukeropplevelsen som er mulig å få til med GraphQL er så god at vi føler oss trygg på at det vil bli langt enklere for sektoren å komme i gang med å bruke informasjon og funksjonalitet fra FS enn noen gang før.

GraphQL har i tillegg ord på seg for å være morsomt å jobbe med, og kan dermed bidra til å gjøre Unit til en mer attraktiv arbeidsgiver.

Innenfor sektoren så vet vi at NSD (Norsk senter for forskningsdata) har brukt GraphQL siden 2018. De rapporterer at dette har vært et svært godt valg som har muliggjort vesentlige kostnadsbesparelser som følge av at det har forenklet jobben med å bygge APIer som tilgjengeliggjør data og funksjonalitet til sektoren og industrien forøvrig.

GraphQL som teknologi har hatt en veldig god vekstkurve siden 2015. Vi ser ingen tegn til at denne veksten er avtagende. Vi viser til artikkelen GraphQL Hype Cycle 2021 som gir en god analyse av dette, samt nedlastingsstatistikk av graphql-pakken fra npm-stat.com som etter vår mening også underbygger denne påstanden. Vi viser også til artikkelen How Netflix Scales its API with GraphQL Federation (Part 1) som viser at Netflix er godt fornøyd og fortsetter sin satsing.

Negative konsekvenser​

Selv om GraphQL snart er 10 år gammelt, så er det fortsatt relativt ny teknologi sammenlignet med alternativene. Dette medfører naturlig nok en risiko for at teknologien ikke er like varig som alternativene. Vi mener at denne risikoen er svært liten og viser til forrige pararaf for å underbygge dette.

Videre er det få av Unit sine utviklere som har erfaring med teknologien, noe som gjør at vi må sette av tid og ressurser til opplæring og erfaringsbygging. Dette er et viktig poeng og dermed noe vi kommer til å sette høyt på dagsorden fremover.

En annen vanlig kritikk av GraphQL er at det er lett å ende opp med ytelsesproblemer som følge av at brukere kan lage spørringer som henter mye forskjellig data i en forespørsel. Vi har sett på dette og konkludert med at dette kan håndteres så lenge man forstår hvordan teknologien virker og er pro-aktiv.

Videre er det mange bekymrer seg for sikkerhetsaspektet. GraphQL-standarden sier bevisst ingenting om sikkerhet og tilgangsstyring. Dette kommer av at sikkerhet bør håndteres i forretningslogikk-laget hvor man sitter med mer kunnskap om hva som er de riktige sikkerhetsbeslutningene. Dette åpner også opp for gjenbruk av sikkerhetskoden på tvers av tjenester. Siden vi uansett skal bygge en plattform med gjennomgående autentisering og sikkerhet så samsvarer dette godt med våre behov. NSD viser for eksempel allerede at det er fullt mulig å integrere GraphQL med Feide.

Sist men ikke minst så er ikke GraphQL godt kjent i sektoren, noe som gjør at vi må sette av tid og ressurser til å kommunisere hvorfor FS går i denne retningen, samt til opplæring og kursing. Her har vi trolig en fordel av at NSD allerede har begynt på denne jobben, og at Uninett også viser stor interesse for mulighetene som ligger i GraphQL.

Fordeler og ulemper ved alternativene​

I tillegg til å dekke alternativene til den anbefalte løsningen, så inneholder dette kapittelet også en grundigere gjennomgang av GraphQL. Dette ligger mot slutten av kapittelet siden vi allerede har tatt for oss hovedpunktene her.

Merk at både OpenAPI og OData er standarder for å bygge REST-APIer. Vi har valgt å ikke evaluere REST i seg selv, da målarkitekturen for FS setter krav til et spesifikasjonsspråk for APIene:

Et viktig krav til APIene i plattformen, uavhengig av teknologi, er at det må foreligge detaljerte spesifikasjoner i et maskinlesbart format. Dette utgjør kontraktene mellom plattformen og brukerne og er dermed helt nødvendige dokument når man skal designe, bygge og forvalte plattformen.

Som nevnt i målarkitekturen, så gjennomførte vi en PoC av "spesifikasjon først"-metodikken. Dette innebærer at man spesifiserer APIet før man begynner å skrive kode. Erfaringen fra dette arbeidet er at denne måten å utvikle APIer på ga vesentlig verdiskapning i form av mellom annet:

  1. Det ble lettere å arrangere arbeidsmøter hvor vi designet APIet i samarbeid med produkteier og andre domeneeksperter. Resultatet fra disse møtene kunne raskt dokumenteres i spesifikasjonsspråket og deretter vises i form av en dokumentasjonsside som var mulig for ikke-tekniske å forstå og kommentere på.
  2. Vi kunne presentere spesifikasjonen (og dokumentasjonssiden) for kunden og dermed få tidlig tilbakemelding på funksjonaliteten vi jobbet med. Dette gjorde at vi oppdaget mange feilaktige antagelser og dermed utbedret flere dårlige designvalg tidlig i prosessen.
  3. Når vi implementere spesifikasjonen så utnyttet vi kodegenerering til å etablere et rammeverk hvor det ble nærmest umulig å bygge APIet på en måte som ikke stemte overens med det vi hadde spesifisert. Vi oppdaget forøvrig ved flere anledninger at spesifikasjonen ikke var mulig å bygge som først planlagt. Disse "kontraksbruddene" ble svært synlige for utviklerne, og ble dermed flagget til produkteier og kommunisert videre.

Den største ulempen var at OpenAPI 3 oppleves som et relativt tungt spesifikasjonsspråk å jobbe med. Se ulemper med OpenAPI for mer info.

OpenAPI​

OpenAPI 3 har etablert seg som bransjestandard for å beskrive REST-APIer. Standarden var i utgangspunktet kjent som Swagger, men fikk nytt navn i forbindelse med at versjon 3 ble lansert i 2017.

Vi har allerede mye erfaring med å bruke både Swagger og OpenAPI. Disse verktøyene blir brukt i forskjellig grad, men i all hovedsak har bruken begrenset seg til dokumentasjonsbruk.

Fordeler​

OpenAPI-spesifikasjonen gjør det mulig å spesifisere REST-APIer slik at man kan generere kode både for API-produsent og API-konsument.

Den samme spesifikasjonen kan i tillegg brukes for å generere dokumentasjonssider som gjør det enklere for utviklere å komme i gang med å bruke APIet.

Det begynner å komme en del gode verktøy som forenkler jobben med å utvikle API-spesifikasjonen. Her snakker vi om for eksempel utvidelser til IntelliJ og VSCode, i tillegg til mer omfattende skybaserte tjenester som for eksempel Redoc.ly og Stoplight. Vi forventer at kvaliteten og brukervennligheten til disse verktøyene vil øke i tiden fremover.

Det å jobbe med OpenAPI-spesifikasjonen bidrar til å fokusere innsatsen på behovene som skal løses.

OpenAPI-spesifikasjonen er designet for å kunne beskrive alle mulige slags REST-APIer. Dermed kan vi bruke den for å beskrive alle våre eksisterende APIer.

Ulemper​

OpenAPI inneholder ikke noe standardisert spørrespråk eller lignende som hjelper oss med å bygge APIer som gir eksponensiell merverdi.

OpenAPI-spesifikasjonen er reaktiv og ikke proaktiv. Den er designet for å kunne beskrive alle mulige slags eksisterende REST-APIer. Her er bredden stor, noe som gjør det relativt tungt å jobbe med spesifikasjonene.

Av samme grunn gir ikke OpenAPI-spesifikasjonen noen føringer for hvordan man skal bygge gode APIer. Vi erfarer at det dermed går bort mye tid på å diskutere og finne ut hvordan man skal løse forskjellige behov ved hjelp av REST og OpenAPI, og det finnes sterke meninger som drar i forskjellige retninger.

Et konsekvens av dette er at det ikke er nok å innføre OpenAPI som standard for APIene i FS-plattformen. Vi må i tillegg utvikle vår egen standard for hvordan de respektive APIene skal bygges opp slik at brukerne av plattformen får opplevelsen av at FS er ett helhetlig og gjennomtenkt produkt.

OData​

I motsetning til OpenAPI, så er OData en standard som dikterer hvordan man skal bygge APIer. Standarden følger likevel REST-prinsippene, noe som gjør at de APIene man utvikler blir enkle å komme i gang med å bruke.

Standarden går tilbake til 2007 og stammer fra SQL Server-gruppen i Microsoft sitt forsøk å lage datatjenester som kunne brukes av nettleseren direkte.

Vi gjorde en evaluering og en PoC av OData høsten 2020 i forbindelse med rapporten FS-arkitektur og modernisering. Resultatet var nedslående, og vi har derfor valgt å ikke se nærmere på denne retningen. Vi oppsummerer raskt fordelene og ulempene fra denne evalueringen under, men viser til rapporten for detaljer.

Fordeler​

OData inneholder et standardisert spørrespråk som gjør det mulig å bygge APIer som gir eksponensiell merverdi.

OData blir brukt internt av Microsoft i deres utviklingsverktøy og i Microsoft Graph. Det er dermed naturlig å tenke at standarden ikke kommer til å forsvinne med det første.

Ulemper​

Standarden er så omfattende at den eneste komplette implementasjonen er Microsoft sin egen implementasjon. Det er derfor ikke forsvarlig å bruke OData med mindre vi går over til å utvikle i .NET.

Videre er den så omfattende at det ikke er mulig/forsvarlig å skrive spesifikasjonen først. Man må i stedet bruke Microsoft sine verktøy for å bygge APIet, og så genereres spesifikasjonen som et resultat av dette. Dermed mister vi fordelene av å kunne jobbe etter spesifikasjon først-metoden.

Det er lav interesse for standarden, og dermed også få gode verktøy for å konsumere APIer som bruker OData, med mindre man bruker Microsoft sine verktøy.

GraphQL​

GraphQL-standarden ble designet av Facebook i 2012 og har vært utviklet som en åpen standard siden 2015. I løpet av disse årene har den blitt adoptert av svært mange aktører, både store og små.

Hovedforskjellen mellom REST og GraphQL er at sistnevnte spesifiserer et API i form av en informasjonsmodell, og et tilhørende spørrespråk som lar konsumenten effektivt hente de delene av informasjonsmodellen som er relevant for seg. Dette har flere viktige effekter:

  1. Det gir API-designeren et kraftig verktøy for å kommunisere hvordan dataene henger sammen
  2. Det gir applikasjonene et kraftig verktøy for å hente alle relevante data på en gang, noe som gir enklere applikasjonskode og bedre ytelse
  3. Det understøtter prinsippet om dataminimering (personopplysningsloven)
  4. Det forenkler forvaltningsjobben ved at informasjon om bruksmønster på attributtnivå muliggjør avvikling og sletting av ubrukt funksjonalitet

Spørrespråket som ligger i kjernen av GraphQL er designet for å være lett å ta i bruk for utviklere som allerede er kjent med JSON. Kraften og mulighetene som ligger i spørrespråket er nøye balansert med behovet for å designe et API med forutsigbar ytelse og sikkerhet. Disse kvalitetene kommer som følge av at standarden ble designet for å kunne brukes direkte av både interne og eksterne brukervendte applikasjoner.

Vi gjorde en evaluering av GraphQL høsten 2020 i forbindelse med rapporten FS-arkitektur og modernisering. Her så vi på trender, verktøy og satte oss inn i teknologien for å forstå hvordan det eventuelt kunne brukes for å fremme FS-moderniseringen. Vi konkluderte med at:

  1. GraphQL er enkelt å komme i gang med som følge av at tilgjengelig dokumentasjon og kurs er av høy kvalitet
  2. Til tross for mulighetene som spørrespråket gir til brukerne så var det relativt enkelt å implementere nødvendig funksjonalitet
  3. Det finnes gode verktøy for å visualisere GraphQL-skjemaet, noe som fremmer samarbeid og kommunikasjon både i design- så vel som overleveringsfasen
  4. Teknologien har jevn vekst og er tatt i bruk av store aktører, så vel som NSD i egen sektor.

Høsten 2021 har vi i tillegg gjennomført en PoC hvor vi gjenskapte deler av APIet vi lager til BOTT-SA. Igjen er konklusjonen at GraphQL er svært velegnet for moderniseringen av FS.

Dette inntrykket blir understøttet av samtalene våre med NSD (Norsk senter for forskningsdata) som tok i bruk GraphQL i 2018. De melder at det er vesentlig lettere å drive API-utvikling ved hjelp av GraphQL sammenlignet med REST og OpenAPI.

gRPC​

Vi har ikke evaluert gRPC. Vi har tenkt at dette valget er bedre egnet for interne APIer og derfor ikke var av relevans for FS-plattformen som er beregnet for ekstern konsumpsjon. Det at gRPC ikke har et standardisert spørrespråk, var også en årsak til at vi ikke så nærmere på dette alternativet.

Lenker og mer informasjon​