API-design i FS-plattformen

FS-plattformen har som mål å tilgjengeliggjøre store mengder data og forretningslogikk. Vi bygger verktøy som gjør at det tekniske utviklingsarbeidet går raskt. For at dette skal resultere i gode APIer som er behagelige for våre og sektorens utviklere å benytte seg av, er det ikke nok å identifisere tabeller i FS og så løfte dem opp i et API.

Viktige prinsipper

Det er noen viktige prinsipper vi legger til grunn når vi designer APIer i FS-plattformen.

Design først

APIer i FS-plattformen skal utvikles design først. Det betyr at all nyutvikling starter med design. Å bruke tid på design, sparer oss for mange kostnader lenger fremme. Dette krever involvering fra domene- eksperter, GraphQL-eksperter og eksperter på bruk av GraphQL-APIer helt fra starten.

Domenedrevet design

I den fasen vi er i nå, handler mesteparten av API-utviklingen om å tilgjengeliggjøre funksjonalitet for å lese og skrive mot den eksisterende FS-databasen. Designet vårt skal imidlertid styres av hvilke forretningsbehov vi prøver å løse, ikke hvordan dataene er strukturert i dagens FS-database.

Selv om det er gjort mye godt design også i FS-databasen, er det flere årsaker til at vi ikke bare skal eksponere strukturen i databasen slik den er:

1. Den beste måten å uttrykke et forretningsbehov i APIet, er ikke nødvendigvis sammenfallende med den beste måten å uttrykke samme behov i databasen
2. Forretningsbehovene kan ha endret seg i tiden etter at databasen ble modellert
3. Selv om FS-modellen stort sett er god, finnes det også feil og mangler her, som vi ikke uten videre skal ta med oss ut til APIet

Prosess først

Når vi designer APIer i FS-plattformen, skal vi alltid ha i bakhodet hvilken arbeidsprosess vi skal støtte. Dette krever at prosessen er tilstrekkelig kartlagt (og dokumentert for eksempel i FS-plattformens prosesskatalog). Arbeidsprosessen danner dermed konteksten rundt designet, og du kan hele tiden ha i tankene hvor du er i prosessen og hva brukeren har behov for.

Utvikleren i sentrum

Sluttbrukeren av APIene våre er de utviklerne som skal lage løsningene som benytter seg av dem. Det betyr at utviklerens opplevelse av APIene er viktig for oss. For API-designprosessen betyr det at vi søker å designe APIer som er lette å forstå og ta i bruk. Det betyr også at vi har fokus på god dokumentasjon, og at domenebegreper er forklart på en presis og lettfattelig måte.

Kontinuerlig forbedring

Kontinuerlig forbedring for oss betyr at:

• Vi søker aktivt ny kunnskap og forsøker å holde oss oppdatert på beste praksis
• Vi søker å bygge nettverk og utveksle erfaringer med andre som jobber med API-design
• Vi utveksler erfaringer og deler kunnskap oss imellom
• Vi søker å designe robute fremoverkompatible APIer, som tåler at vi gjør endringer fortløpende etterhvert som vi lærer

Viktige kompetanser

For at vi skal få til dette, er vi avhengig av folk med forskjellig kompetanse er involvert og samarbeider.

API-design krever kjennskap til forretningsbehovene som skal løses

Vi designer APIer for å støtte forretningsbehov. For å gjøre et godt design, bør du derfor ha tilgjengelig personer som kjenner det aktuelle domenet og forretningsområdet godt, og som kan svare på spørsmål som måtte dukke opp underveis i prosessen.

API-design i FS-plattformen krever kjennskap til FS

For å få til et godt design for et API i FS-plattformen, bør du enten ha inngående kjennskap til FS-databasen eller ha tilgang på personer som har det. For APIer som skal hente data fra FS, trenger man særlig god kunnskap om relasjoner mellom tabeller i FS. For APIer som skal skrive til FS, trenger man i tillegg kunnskap om interne forretningsregler i form av triggere og constraints i FS-databasen.

API-design i FS-plattformen krever kjennskap til studieadministrativ terminologi

APIets brukere er utviklere som ikke kjenner FS, og som ikke kjenner domenet. Dette betyr at vi ikke ukritisk kan gjenbruke FS-databasens navn på tabeller og kolonner for å lage typer og felter i APIene. Det er viktig at navngiving legges nært opp til dagligtale der det mulig. Vi foretrekker å bruke begreper som er kjent fra før i det studieadministrative domenet, fremfor å lage våre egne. Når vi bruker domenespråk eller mer FS-internt språk, er det viktig at disse er forklart i API-spesifikasjonen, og gjerne med lenker til prosesskatalogen eller begrepskatalogen der det er hensiktsmessig.

API-design krever kjennskap til skjemaspråket APIet skal defineres i

Sluttproduktet av et API-design vil alltid være et API-skjema. I FS-plattformen i dag har vi støtte for OpenAPI/REST og GraphQL, som har hvert sitt skjemaskpråk. Det betyr at den som gjør API-designjobben, må kunne skrive et slikt skjema, eller en spesifikasjon som en utvikler kan oversette til et skjema. Når vi designer APIet er det også viktig å kjenne til muligheter og begrensninger i skjemaspråket og andre standarder, arkitekturprinsipper og etablert praksis som gjelder for teknologiene vi bruker.

API-design krever kjennskap til hvordan APIene implementeres

Selv om vi i stor grad bruker kodegeneratorer for implementasjon av APIene i FS-plattformen, vil det være en fordel å inkludere personer med kjennskap til hvordan APIene implementeres i designprosessen, for å unngå design som oppmuntrer brukerne til uheldige spørremønstre og dårlig ytelse.

API-design krever kjennskap til hvordan APIene skal brukes

Å sette utvikleren i sentrum betyr at vi må involvere utviklere som har kjennskap til hvordan APIet skal brukes i designprosessen når vi kan, og innhente tilbakemeldinger fra de som tar APIene i bruk. Testing hos kunde og utrulling av ny funksjonalitet bør skje på en slik måte at vi har tid til å utføre forbedringer basert på tilbakemeldinger fra utviklerne.

Hvordan vi jobber med API-design

API-design i FS-plattformen krever altså tverrfaglig kompetanse og dermed godt samarbeid. Hvordan vi velger å organisere arbeidet i praksis, vil variere ut fra hvilken kompetanse man har tilgjengelig internt og eksternt. Våre erfaringer tilsier også at det ikke er klare grenser mellom hva som kan gjøres av en utvikler og hva som kan gjøres av en person med domenekompetanse. For eksempel erfarer vi at GraphQL-skjemaspråket er lett å lære, også for personer uten IT-bakgrunn.

Følgende er eksempler på måter vi har hatt god erfaring å jobbe med API-design på:

• Et utviklingsteam jobber sammen i workshop med produkteier eller annen domenerepresentant til stede
• Produkteier eller annen person med domenekompetanse skriver skjema direkte, og får innspill fra utviklere på teamet gjennom ordinær codereview-prosess
• Utvikler skriver skjemaet og involverer produkteier eller andre domenerepresentanter ved behov samt i codereview-prosess

Det uansett sterkt anbefalt at minst én person med domenekompetanse og én med utviklingskompetanse deltar i codereview-prosessen rundt API-design.