Migrere fra FS-APIet til FS GraphQL API
Her finner du informasjon om hvordan du kan gå fram for å migrere fra FS-APIet til FS GraphQL API.
Du kan beholde API-brukeren din
API-brukere som har tilgang til FS-APIet kan også brukes mot FS GraphQL API. Du bestiller tilgang til FS GraphQL API på vanlig måte. Når du bestiller tilgang til FS GraphQL API, er det viktig at du spesifiserer hvilke data du ønsker tilgang til. Les mer her: Hvordan får jeg tilgang?
Konstruer en relevant GraphQL-spørring for henting av data
FS-APIet er bygget opp av ressurser som ligger ganske nær tabellstrukturen i FS. Responsen for de fleste GET-operasjoner vil inneholde lenker til API-kall for å hente relevante grunnlagsdata. For å hente alle relevante data, må du derfor ofte gjøre mange separate HTTP-kall.
I GraphQL har du imidlertid mulighet til å konstruere spørringer som henter nøstede data. Du bør derfor ikke nødvendigvis lete etter spørringer eller oppslag som nøyaktig samsvarer med API-kallene du gjør i dagens løsning. Grunnlagsdata vil som regel være mulig å hente direkte i kontekst av hovedspørringen.
Les mer om spørringer i FS GraphQL API her: FS GraphQL API: Spørringer
Paginering i FS GraphQL API
FS-APIet benytter sidebasert paginering. Det vil si at du spesifiserer hvor mange resultater du vil ha per side, og deretter hvilken side du vil ha tilbake. FS GraphQL API benytter cursor-basert paginering. Det betyr at hver rad i resultatet ditt får et bokmerke, og når du skal bla i pagineringen, ber du alltid om et visst antall rader etter et bestemt bokmerke.
Les mer her: FS GraphQL API: Paginering
Finn en relevant skriveoperasjon
Skriveoperasjoner i FS-APIet følger vanlig REST-mønster med POST, PATCH og DELETE på spesifikke ressurser. Mutasjonene i FS GraphQL API følger et annet mønster. Mutasjonene er knyttet til studieadministrative arbeidsprosesser, og en mutasjon vil typisk svare til en handling som utføres i en slik prosess.
Les mer her: FS GraphQL API: Mutations
Klienten må bruke FS GraphQL APIs ID for objektet
FS GraphQL API bruker andre IDer enn FS-APIet. Det betyr at klienten kan måtte gjøre et oppslag mot FS GraphQL API for å finne APIets ID, før man kan utføre selve skriveoperasjonen. For endepunkter som er varslet avviklet, vil det som regel finnes et oppslag som tar inn FS-APIets ID, og som returnerer objektet med FS GraphQL APIs id.
Eksempelvis er personløpenummer IDen for personer i FS-APIet. Slik finner du IDen for person-profil for personen med personløpenummer 1440 i FS GraphQL API:
query FinnIdGittPersonlopenummer {
personProfilerGittPersonlopenumre(
eierInstitusjonsnummer: "1234"
personlopenumre: "1440"
) {
id
}
}
Dette gir følgende respons:
{
"data": {
"personProfilerGittPersonlopenumre": [
{
"id": "NzY6MTIzNCwxNDQw"
}
]
}
}
Kontakt FS-support dersom du ikke finner et oppslag som passer til behovet ditt.
Abonnere på hendelser
FS-APIet har støtte for å sende meldinger til en meldingskø når det skjer endringer i database. FS GraphQL API har en løsning for det samme behovet, men det er løst på en annen måte. Det er to hovedforskjeller på FS-APIet og FS GraphQL API her.
For det første er hendelsene i FS GraphQL API designet som trinn i en studieadministrativ prosess, der FS-APIet er forholder seg til CRUD-hendelser (INSERT, UPDATE, DELETE) i databasen. Det betyr at GraphQL-hendelsene stort sett vil være mer spissede enn FS-API-meldingene. Det betyr også at du kan måtte lytte på flere hendelser i FS GraphQL API for å erstatte meldingskø-funksjonaliteten for en gitt ressurs. Det betyr imidlertid også at klienten får mer informasjon om hva som faktisk har skjedd, og kan reagere mer presist, og at du får færre falske positiver.
For det andre så baserer FS-APIet sin hendelsesarkitektur seg på mønsteret for meldingsforsendelse, mens FS GraphQL APIet baserer seg på mønsteret for spørring og oppslag. Se Digitaliseringsdirektoratets Referansearkitekturer for detaljer.
Dette valget har vi gjort for å kunne levere en enklere og mer fleksibel brukeropplevelse til brukergrupper som tåler å vente i mer enn et par sekunder med å få vite at hendelser har oppstått. Våre undersøkelser viser at dette treffer de aller fleste av behovene som FS GraphQL API skal levere på.
Mønsteret for meldingsforsendelse vil kunne bli støttet på et senere tidspunkt, men det har foreløpig ikke vært prioritert. Dersom dere har konkrete behov som krever dette så ønsker vi å komme i kontakt for å diskutere dette.
Les mer her: [FS GraphQL API: Hendelser]
Hva om mitt behov ikke er dekket?
Vi vil normalt ikke varsle avvikling av hele eller deler av et API før vi er trygge på at tilsvarende funksjonalitet er på plass i FS GraphQL API. Dersom du likevel opplever at behovet ditt ikke er dekket i det nye APIet, ber vi om at du tar kontakt med fs-support@sikt.no og beskriver behovet.
FS-APIet vil avvikles gradvis og over tid, etterhvert som funksjonalitet blir tilgjengelig i FS GraphQL API. Det vil si at mange klienter må forholde seg til å bruke en kombinasjon av begge APIene i en overgangsperiode.
Kontakt FS-support for hjelp ved behov
Kontakt fs-support@sikt.no dersom du trenger hjelp til å komme i gang, eller underveis i migreringen.
Eksempler
Her vil du finne eksempler på hvordan du kan erstatte endepunkter i FS-APIet med kall mot FS GraphQL API. Merk at GraphQL gir stor fleksibilitet i hvilke data du kan hente, så bruk eksemplene som utgangspunkt, og konstruer en spørring skreddersydd for ditt behov.
GET /akseptansetyper
Dokumentasjon av endepunktet i FS GraphQL API Eksempel på GraphQL-kall som henter akseptansetyper:
query MyQuery {
samtykkekrav(eierInstitusjonsnummer: "1234") {
edges {
cursor
node {
aktiv
id
sporsmal {
eng
nno
nob
}
forklaring {
eng
nno
nob
}
}
}
}
}
Eksempel på svar:
{
"data": {
"samtykkekrav": {
"edges": [
{
"cursor": "MToxMjM0LEZMUg",
"node": {
"aktiv": false,
"id": "MToxMjM0LEZMUg",
"sporsmal": {
"eng": "Do you accept that information about your ID will be sent \"Joint Library Card\"?",
"nno": "Godtar du at informasjon om deg skal overførast til Felles Låneregister?",
"nob": "Godtar du at informasjon om deg skal overføres til Felles Lånerregister?"
},
"forklaring": {
"eng": "This service requires a norwegian ID-number. If you have a norwegian ID-number and you accept the following question, you may also use your studentcard as library-card on other libraries.",
"nno": "Dersom du svarer \"Ja\" kan du også bruke studentkortet ditt som lånekort på andre bibliotek som er med i ordninga.",
"nob": "Hvis du svarer \"Ja\" kan du også bruke studentkortet ditt som lånekort på andre bibliotek som er med i ordningen."
}
}
},
{
"cursor": "MToxMjM0LE5FVFRQVUJM",
"node": {
"aktiv": false,
"id": "MToxMjM0LE5FVFRQVUJM",
"sporsmal": {
"eng": "Do you want to have your name and your email address listed in the institution's directory service?",
"nno": "Ønskjer du at namnet ditt og e-postadressa di skal vere tilgjengeleg via personsøkjetenesta ?",
"nob": "Ønsker du å gjøre ditt navn og din e-postadresse tilgjengelig via institusjonens personsøketjeneste?"
},
"forklaring": {
"eng": "The institution has an electronic, searchable directory of employees and students. By using the search engine, information about students' e-mail addresses, usernames, their faculty/department/programme and the URL for home pages, will appear if they exist. <BR>The information will be collected from FS (the student directory).<BR>The directory is accessible through the Internet. According to the Norwegian Personal Data Act, consent from the individual the data can be related to must be collected before this individual can be included in the directory services.",
"nno": "Institusjonen har ein elektronisk katalog kor det er mogeleg å søkje etter tilsette og studentar. For ein student som er registrert i denne katalogen, vil personsøk på nettsidene til institusjonen vise e-postadresse, brukarnamn, kva for ei eining studenten er knytte til og URL for eventuell heimeside på nettet til institusjonen.<BR>Det er frivillig å vere oppført i katalogen. Dersom du samtykkjer, vil du vere oppført i katalogen fram til brukarkontoen din ved institusjonen blir avslutta. Samtykkjet kan kva tid som helst trekkjast tilbake.",
"nob": "Institusjonen har en elektronisk søkbar katalog over sine studenter og ansatte. For en student som er registrert i denne katalogen, vil personsøk på institusjonens nettsider vise studentens e-postadresse, brukernavn, enhetstilknytning og URL for eventuell hjemmeside på institusjonens nett.<BR>Det er frivillig å være oppført i katalogen. Hvis du samtykker, vil du være oppført i katalogen frem til brukerkontoen din ved institusjonen opphører. Samtykket kan når som helst trekkes tilbake."
}
}
},
{
"cursor": "MToxMjM0LFJFU1VUVkVLU0w",
"node": {
"aktiv": false,
"id": "MToxMjM0LFJFU1VUVkVLU0w",
"sporsmal": {
"eng": "Do you accept that this institution can fetch result information from other Norwegian institutions?",
"nno": "Ønskjer du å åpne for at institusjonen skal kunne hente resultatinformasjon om deg frå andre institusjonar?",
"nob": "Ønsker du å åpne for at institusjonen skal kunne hente resultatinformasjon om deg fra andre institusjoner?"
},
"forklaring": {
"eng": "If you answer \"Yes\" to this question you will allow this institution to gather exam-information about you from other Norwegian institutions. <p><a href=\"http://www.fellesstudentsystem.no/dokumentasjon/rutiner/resultatutveksling/studentrutiner-en.html\" target=\"_blank\">Click here for more information about exchange of results</a></p>",
"nno": "Dersom du svarer \"Ja\" på dette, så tillet du at det blir henta inn informasjon om dine resultater frå andre nasjonale institusjonar du har gått på.<p><a href=\"http://www.fellesstudentsystem.no/dokumentasjon/rutiner/resultatutveksling/studentrutiner-ny.html\" target=\"_blank\">Klikk her for mer info om resultatutveksling</a></p>",
"nob": "Hvis du svarer \"Ja\" på dette, så tillater du at det blir hentet inn informasjon om dine resultater fra andre nasjonale institusjoner du har gått på. <p><a href=\"http://www.fellesstudentsystem.no/dokumentasjon/rutiner/resultatutveksling/studentrutiner.html\" target=\"_blank\">Klikk her for mer info om resultatutveksling</a></p>"
}
}
},
{
"cursor": "MToxMjM0LFNFTUtWSVRU",
"node": {
"aktiv": false,
"id": "MToxMjM0LFNFTUtWSVRU",
"sporsmal": {
"eng": "I want to order a paper version of the semester card",
"nno": "Eg ynskjer å bestille semesterkvittering i papirformat",
"nob": "Jeg ønsker å bestille semesterkvittering i papirformat"
},
"forklaring": {
"eng": "<b>New from autumn semester 2015:</b> Student ID with photo and semester receipt is now available as an app for Android and IOS phones.</br></br>\r\n\r\nIt is not necessary to present the student ID app or a valid semester receipt at exams. \r\n\r\n<a href=\"http://www.uib.no/studentid\" target=\"_blank\">You can download the app here!</a></br></br>\r\n\r\nIf you still need a paper version of the semester receipt you can order this below. The semester receipt will be sent to your semester address. Please make sure to update your semester address here at StudentWeb.\r\n",
"nno": "<b>Nytt fra haustsemesteret 2015:</b> Semesterkvittering og studentbevis får du no på app for Android- og IOS-telefoner.</br></br> \r\n\r\nDet er ikkje naudsynt å syne fram studentbevisappen eller anna semesterkvittering ved eksamen</br></br>\r\n\r\n<a href=\"http://www.uib.no/studentbevis\" target=\"_blank\">Du kan laste ned appen her!</a></br></br>\r\n\r\nDersom du likevel har bruk for semesterkvittering på papir, kan dette bestillast under. Semesterkvitteringa vil bli sendt til di semesteradresse. Husk å oppdatere di semesteradresse her på StudentWeb.\r\n",
"nob": "<b>Nytt fra høstsemesteret 2015:</b> Semesterkvittering og studentbevis får du nå på app for Android- og IOS-telefoner. </br></br> \r\n\r\nDet er ikke nødvendig å vise frem studentbevisappen eller annen semesterkvittering ved eksamen.</br></br>\r\n\r\n<a href=\"http://www.uib.no/studentbevis\" target=\"_blank\">Du kan laste ned appen her!</a></br></br>\r\n\r\nDersom du likevel har behov for semesterkvittering på papir kan dette bestilles under. Semesterkvitteringen vil bli sendt til din semesteradresse. Husk å oppdatere din semesteradresse her på Studentweb."
}
}
}
]
}
}
}
GET /studieretninginfoer
Dokumentasjon av endepunktet i FS-APIet Dette endepunktet er lite brukt, men er laget primært for å hente informasjon til nettsideløsninger. Her er et eksempel på et API-kall som henter ut studieretninginfoer som er klare for publisering høsten 2024:
query MyQuery {
publiseringsklareStudieprogram(
filter: {eierInstitusjonsnummer: "1234", kanPubliseres: true, terminer: {arstall: 2024, terminbetegnelse: "HØST"}}
) {
edges {
node {
id
studieprogram {
kode
studieretninger {
studieretning {
navn {
nob
nno
eng
}
}
beskrivelser {
id
innhold
publiseringstag
rekkefolgenummer
sprak {
iso6392Kode
}
}
}
}
}
}
}
}
Eksempel på svar:
{
"data": {
"publiseringsklareStudieprogram": {
"edges": [
{
"node": {
"id": "MjE0OjEyMzQsQkZZLU5UTlUsSMOYU1QsMjAyMA",
"studieprogram": {
"kode": "BFY-NTNU",
"studieretninger": [
null
]
}
}
},
{
"node": {
"id": "MjE0OjEyMzQsTVNQUk9HNTgsSMOYU1QsMjAyMA",
"studieprogram": {
"kode": "MSPROG58",
"studieretninger": [
{
"studieretning": {
"navn": {
"nob": "Sen høst",
"nno": null,
"eng": null
}
},
"beskrivelser": [
{
"id": "MTExOjEyMzQsTVNQUk9HNTgsU0VOIEjDmFNULElOTkhPTEQsQk9LTcOFTCwyMDIzLEjDmFNU",
"innhold": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce vehicula, orci aliquet pharetra ultricies, dolor urna vestibulum risus, id malesuada magna purus non nunc. Integer pellentesque eu libero et interdum. Ut turpis nisi, sollicitudin non urna ut, consequat auctor felis. Etiam lobortis purus id maximus sodales. Suspendisse ex arcu, tempus at enim ut, ultricies faucibus enim. In orci orci, commodo at porta sit amet, sagittis ac diam. Maecenas tincidunt vestibulum mi quis elementum. Vestibulum nisl magna, porta at augue eu, gravida vestibulum ipsum. Vivamus ac varius ante. Nulla felis est, auctor sit amet laoreet ac, viverra eu erat. Aliquam ac ligula varius, condimentum ipsum sed, scelerisque ex. Mauris porta faucibus placerat. Mauris pretium augue id interdum sollicitudin. Integer tincidunt dui a sem efficitur feugiat. Donec a elementum libero. Fusce a eleifend velit. Nulla facilisi. Donec elementum lectus sed vulputate congue. Suspendisse faucibus pharetra volutpat. Maecenas pellentesque tellus eros, quis molestie velit tincidunt bibendum. Integer ut porta nisi, id lacinia orci. Fusce a finibus ipsum, nec mollis neque. In id quam vel dui consectetur interdum. Donec tempor maximus libero, ac congue mauris laoreet sed. Nam laoreet massa quis gravida tempus. Vivamus vehicula vulputate aliquet. Aenean rutrum nibh nec lacus ullamcorper bibendum. Phasellus vel sodales libero, sed blandit turpis. Etiam consectetur egestas massa at viverra.",
"publiseringstag": "innhold",
"rekkefolgenummer": 15,
"sprak": {
"iso6392Kode": "NOB"
}
}
]
},
{
"studieretning": {
"navn": {
"nob": "Tidlig høst",
"nno": null,
"eng": null
}
},
"beskrivelser": [
{
"id": "MTExOjEyMzQsTVNQUk9HNTgsVElETElHIEjDmFNULElOTkhPTEQsQk9LTcOFTCwyMDE5LEjDmFNU",
"innhold": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce vehicula, orci aliquet pharetra ultricies, dolor urna vestibulum risus, id malesuada magna purus non nunc. Integer pellentesque eu libero et interdum. Ut turpis nisi, sollicitudin non urna ut, consequat auctor felis. Etiam lobortis purus id maximus sodales. Suspendisse ex arcu, tempus at enim ut, ultricies faucibus enim. In orci orci, commodo at porta sit amet, sagittis ac diam. Maecenas tincidunt vestibulum mi quis elementum. Vestibulum nisl magna, porta at augue eu, gravida vestibulum ipsum. Vivamus ac varius ante. Nulla felis est, auctor sit amet laoreet ac, viverra eu erat. Aliquam ac ligula varius, condimentum ipsum sed, scelerisque ex. Mauris porta faucibus placerat. Mauris pretium augue id interdum sollicitudin. Integer tincidunt dui a sem efficitur feugiat. Donec a elementum libero. Fusce a eleifend velit. Nulla facilisi. Donec elementum lectus sed vulputate congue. Suspendisse faucibus pharetra volutpat. Maecenas pellentesque tellus eros, quis molestie velit tincidunt bibendum. Integer ut porta nisi, id lacinia orci. Fusce a finibus ipsum, nec mollis neque. In id quam vel dui consectetur interdum. Donec tempor maximus libero, ac congue mauris laoreet sed. Nam laoreet massa quis gravida tempus. Vivamus vehicula vulputate aliquet. Aenean rutrum nibh nec lacus ullamcorper bibendum. Phasellus vel sodales libero, sed blandit turpis. Etiam consectetur egestas massa at viverra.",
"publiseringstag": "innhold",
"rekkefolgenummer": 15,
"sprak": {
"iso6392Kode": "NOB"
}
}
]
}
]
}
}
}
]
}
}
}