Felles Studentsystem - FS-API

Hjelp til oppsett av Felles Studentsystem sitt FS-API.

Om API-et

Felles Studentsystem er en fellestjeneste i sektoren. Hver institusjon har sin instans, men FS leverer et felles REST API for alle institusjoner, der hver institusjon får ut sine studiedata.

Se fellesstudentsystem.no for mer informasjon om tjenesten. Se mer detaljer om FS API.

Miljøer

Det finnes tre varianter av FS-API:

Miljø	URL
Produksjon	https://api.fellesstudentsystem.no/
Test/Demo	https://api-test.fellesstudentsystem.no/
Utvikling	https://api-utv.fellesstudentsystem.no/

Besøk /version for å se hvilken versjon miljøet kjører.

Oppsett av FS-API

Tilgang til FS-API

Du som er lokal tjenesteeier for FS må be FS sentralt om tilgang til FS-API for din institusjon.

Ta kontakt med fs-support@sikt.no med ønske om å få opprettet et brukernavn og passord til FS-API for databasen det er aktuelt å sette opp tilgang til (prod/demo). apigateway er et forslag til et beskrivende brukernavn. Denne bør ha lesetilgang til alle ressurser. Ved behov kan skrivetilganger legges på senere.

Konfigurasjon av FS-API i Gravitee

Se den generelle veilederen.

1. General: Sørg for at context-path tydelig peker på miljøet du setter opp API-et for, f.eks. /fs-api-test eller /fs-api-prod
2. General: Sett navn og beskrivelse
3. General: Sett version til 1
4. Gateway: Finn URL i miljøoversikten og fyll den inn under backend
5. Plan: Vi lager en plan som gir full lesetilgang. Senere kan det lages mer nedlåste planer.
6. Plan: Sett f.eks. navnet til Full lesetilgang
7. Plan: Velg Security type: API key
8. Plan: Auto validate subscription skal IKKE være på
9. Plan: La Characteristics, rate limit og quota være tomme
10. Plan: Legg til Ant pattern /** og method GET
11. Doc: Hopp over dette steget. Dokumentasjon kan lastes opp senere.
12. Deployment: Velg Create and start the API
13. Konfigurer API-et til å autentisere med brukernavnet og passordet fra steg 1
14. Følg veiledningen for konfigurering av backend
15. FS-API forventer basic access authentication, altså skal det settes en Authorization-header med en verdi som vil minne om Basic YnJ1a2VybmF2bjpoZWlwYWFkZWc

Test av API-et

1. Følg veiledningen for å få tilgang til et API og godkjenn selv tilgangen
2. Finn API-nøkkelen som gir tilgang til FS-API og riktig context-path
3. Sjekk at du får hentet ut en liste over emner:

   curl --include -H "X-Gravitee-Api-Key: DIN-NØKKEL" https://gw-INSTANS.intark.uh-it.no/CONTEXT-PATH/emner/
   Bytt ut DIN-NØKKEL, INSTANS og CONTEXT-PATH. Om du får tilbake noe som starter med "HTTP 200" og en JSON-formatert liste med ulike emner, fungerer alt som det skal.
4. Sjekk at API-et krever autentisering:

   curl --include -H "X-Gravitee-Api-Key: DIN-NØKKEL" https://gw-INSTANS.intark.uh-it.no/CONTEXT-PATH/emner/
   Dette burde gi HTTP 401 og {"message":"Unauthorized","http_status_code":401}.

Grunnoppsett for FS Gemini API

Dette er et grunnoppsett mot FS Gemini API'et. Oppsettet kommer med en plan til bruk sammen med ServiceNow. Det er et oppsett satt opp mot produksjonsmiljøet, samt et oppsett satt opp mot utviklingsmiljøet.

Før import: Context path er satt til /fs/gemini og /preview/fs/gemini. Endre eventuelt denne om man benytter en annen context path struktur.

Etter import: Oppsettet bruker API properties til å hente brukernavn og passord, og dette må derfor settes etter import av oppsettet:

1. Gå til Design på API-menyen
2. Gå videre til PROPERTIES i menyen oppe til høyre
3. Legg inn bas64 encoded string av bruker:passord i verdifeltet til fs_fsapi_api_key
4. Endre til encrypted
5. Husk å lagre

Konfigurasjon av meldingskø

Les først om RabbitMQ og (selvbetjeningsløsningen for RabbitMQ)[/docs/datadeling/teknisk-plattform/brom].

FS har mer teknisk informasjon om sin støtte for meldingskøer. Spesielt relevant er avsnittet om Integrasjonspunkter.

Opprette applikasjonen i selvbetjeningsportalen

1. Se veiledningen for å opprette en applikasjon i selvbetjeningsløsningen ved behov.
2. Bruk FS som navn uansett hvilket miljø (prod/test) du skal sette opp. Miljøtypen blir uansett automatisk lagt på som en del av navnet. Et testmiljø med navn FS får f.eks. identifikatoren system-test-fs.
3. Under Publisering, velg Registrering notfikikasjonskilde
   1. Som Lenke til side med dokumentasjon, bruk f.eks. denne lenka
   2. Oppgi en sentral e-postadresse til IT hos egen institusjon
   3. Alle andre felt kan stå tomme
4. Under fanen Applikasjonsinfo finnes nå brukernavn og passord

Konfigurasjon av meldingskø i FS

1. Åpne FS-klienten mot miljøet det skal settes opp meldingskø mot

2. Finn menyvalget WS Tjeneste

3. Opprett en tjenestekode kalt MQ med:

   • URL: amqps:mq-INSTANS.intark.uh-it.no port:5671 vh:system-MILJØ-fs ex:outgoing_system-test-fs

     INSTANS erstattes med din institusjonskode og system-MILJØ-fs matcher navnet på tjenesten som er opprettet i selvbetjeningsportalen.

   • Brukernavn og passord fra selvbetjeningsportalen

4. Opprett en tjenestekode kalt WSINTERN med:

   • URL: https://api.fellesstudentsystem.no for produksjon, eller
   • URL: https://fsapi-test.uio.no for test

   Denne er lik URL-en til API-et hos FS, uten skråstrek på slutten.

5. Ta kontakt med fs-support@sikt.no for videre konfigurasjon på FS sin side.

Test av meldingskøoppsett

For å sjekke at meldinger kommer gjennom, bør det eksisterende en applikasjon som abonnerer på FS sine meldinger via selvbetjeningsløsningen. Abonnentet må være godkjent av en av de som står som eiere av FS i selvbetjeningsløsningen.

1. Gå til applikasjonen som har abonnert på FS-meldinger
2. Verifiser at system-MILJØ-fs ligger under Godkjente abonnement under Abonnere
3. Følg lenka til RabbitMQ sitt brukergrensesnitt under Applikasjonsinfo
4. Logg på med applikasjonens brukernavn og passord
5. Ved nedtrekksmenyen Virtual host øverst til høyre, velg system-MILJØ-fs
6. Finn køen med navn from_system-MILJØ-fs. Under Messages kan man se antall meldinger som ligger i kø. Denne skal øke om det gjøres endringer i FS, med noe forsinkelse (0-5 minutter).