Analysere arbeidsprosesser
Når du er ferdig med dette steget, skal det:
- finnes en beskrivelse av arbeidsprosessen du jobber med, i prosesskatalogen
- være dokumentert for hvert steg hvilke lesebehov og skrivebehov som må dekkes i APIet
Sjekk prosesskatalogen
API-design i FS-plattformen starter alltid med en studieadministrativ arbeidsprosess. Normalt kartlegger vi arbeidsprosesser i samarbeid med sektordeltagere. En arbeidsprosess som er kartlagt, skal ha en oppføring i prosesskatalogen. Hvis en slik oppføring ikke finnes, legger du den til. Hvis den finnes, sjekk at den inneholder følgende:
- En steg-for-steg-beskrivelse av prosessen
- For hvert steg: Hvilke aktører er involvert, og hvordan samhandler de
- Hvilke applikasjoner eller brukergrensesnitt vet vi om som er involvert i denne prosessen?
I denne håndboka vil vi ta utgangspunkt i den delen av prosessbeskrivelsen Betale semesteravgift som handler om å registrere at semesteravgiften er betalt ved en annen institusjon.
Analysere databehov
Før vi kan komme i gang med selve API-designet, må vi gå gjennom hvert steg i prosessen og stille oss følgende spørsmål:
- Lesebehov: Hvilke data trenger brukeren fra FS for å komme videre i prosessen?
- Skrivebehov: Hvilke data må skrives tilbake til FS for at prosessen skal gå videre?
- Forretningsregler: Finnes det regler for hva brukeren har lov og ikke lov til å gjøre i steg i prosessen?
I dette eksempelet kan vi se for oss følgende arbeidsflyt:
- Studenten dokumenterer ekstern betaling av semesteravgift
- Saksbehandler mottar dokumentasjonen, og sjekker at semesteravgiften er betalt til en institusjon som er godkjent for å motta semesteravgift
- Saksbehandler sjekker om studenten er semesterregistrert og har betalt
- Saksbehandler registrerer hvilken institusjon semesteravgiften er betalt til. Kun institusjoner som er godkjent for å motta semesteravgift skal aksepteres her.
Teknologivalg
Dette er en teknisk oppgave, og ikke en designsak, men hva som besluttes her, har litt å si for hvordan vi går videre. Pass på at riktig teknisk kompetanse er involvert i denne beslutningen.
Hva slags API skal vi lage for å løse lese- og skrivebehovene? Vi tror at GraphQL kan brukes til det meste, og tror at GraphQL skal være hovedløsningen vår, men vi er også åpne for at enkelte behov kan løses bedre med annen teknologi. FS-plattformen har også støtte for OpenAPI/REST-baserte APIer, og det er også mulig å utforske andre teknologier.
Følgende er imidlertid viktig:
- Prinsippene for navngiving av felter og objekter bør være de samme på tvers av FS-plattformen
- IDer skal være konsistente på tvers av plattformen, slik at APIene kan brukes i kombinasjon med hverandre
Følger vi disse prinsippene, blir det også mulig å bruke en kombinasjon av forskjellige teknologier for samme prosess. Dersom vi kommer fram til at enkelte deler av prosessen løses best i et REST-API, kan vi likevel løse andre deler i GraphQL.