Gå til hovedinnhold

Fra REST/OpenAPI til FS GraphQL API

Sikt tilbyr flere REST/OpenAPI-baserte APIer med data fra FS. De fleste av dem blir i sin helhet erstattet av FS GraphQL API. Denne siden er startpunktet: her finner du guiden for ditt API, fristen som gjelder for det, og de forskjellene mellom REST og GraphQL som oftest overrasker.

Kjenner du GraphQL fra før, kan du hoppe rett til tabellen under. Er GraphQL nytt for deg, start med Hva er GraphQL? og Kom i gang.

Finn guiden for ditt API​

Hver guide viser de gamle endepunktene side om side med spørringen eller mutasjonen som erstatter dem, med eksempel-spørring og eksempel-svar.

Migreringsguider for REST/OpenAPI-baserte FS-APIer, med avviklingsstatus
TjenesteMigreringsguideStatus
Gammelt FS-APIFra FS-APIet til FS GraphQL APIAvvikles etter 31. mars 2027. Enkelte endepunkter er allerede slått av.
FSWS-CRUDFra FSWS-CRUD til FS GraphQL APIHar passert støttefristen (end of service 31. mars 2026). Vi gir ikke lenger brukerstøtte og retter ikke feil. Tjenesten er ikke slått av.
FSWS-StudrappFra FSWS-Studrapp til FS GraphQL APIVidereutvikles ikke. Enkeltoperasjoner er varslet avviklet etter 31. mars 2027.
GeminiFra Gemini til FS GraphQL APIFlere endepunkter er allerede slått av. Øvrige, blant annet GET /personer og POST /personer, avvikles etter 31. mars 2027.
FSWS-BASFra FSWS-BAS til FS GraphQL APIAvvikles etter 31. mars 2027. Flere operasjoner er allerede slått av og returnerer feil i dag.
FSWS-BRISFra FSWS-BRIS til FS GraphQL APIAvvikles etter 31. mars 2027.
FSWS-HovedbokFra FSWS-Hovedbok til FS GraphQL APIAvvikles etter 31. mars 2027.
FSWS-AlumniFra FSWS-Alumni til FS GraphQL APIAvvikles etter 31. mars 2027.
FSWS-FC (Feide Connect)Fra FSWS-FC til FS GraphQL APIAvvikles etter 31. mars 2027.
FSWS-fskode (institusjonsregisteret)Fra FSWS-fskode til FS GraphQL APIAvvikles etter 31. mars 2027.
FSWS-Feide SemregFra FSWS-Feide Semreg til FS GraphQL APIAvvikles etter 31. mars 2027.
FSWS-Studinfo2 (REST)Fra FSWS-Studinfo2 (REST) til FS GraphQL APIHar passert støttefristen (end of service 31. mars 2026) for REST-varianten. Vi gir ikke lenger brukerstøtte og retter ikke feil. REST-varianten er ikke slått av, men SOAP-varianten er allerede avviklet (24.04.2025).
FSWS-CDM (REST)Fra FSWS-CDM (REST) til FS GraphQL APIAvvikles etter 31. mars 2027 for REST-varianten. SOAP-varianten er allerede avviklet (24.04.2025).
Datoene gjelder per operasjon, ikke bare per tjeneste

Enkeltoperasjoner kan ha tidligere frist enn tjenesten de tilhører. Den autoritative oversikten er avviklingsloggen, som viser Forhåndsvarslet, Varslet, End of Service og Avviklet per operasjon. Se også Sikts avviklingspraksis for hva de forskjellige statusene betyr. «Avvikles etter [dato]» betyr end of service: etter den datoen gir vi ikke lenger brukerstøtte og retter ikke feil. Tjenesten kan fortsatt være i drift en periode etterpå, men den bør ikke brukes.

Migrerer du fra FSWS-LMS, FSWS-DigEks eller FSWS-lk, finnes det ingen egen guide ennå. Framgangsmåten under gjelder likevel — kontakt fs-support@sikt.no med hvilke operasjoner du bruker, så hjelper vi deg å finne de tilsvarende feltene.

Slik går du fram​

  1. Les dokumentasjonen av GraphQL-APIet. Start med Kom i gang, Spørringer og Mutasjoner.

  2. Få oversikt over hvilke data du trenger å lese og skrive. Ta utgangspunkt i dataene klienten faktisk bruker, ikke i endepunktene den kaller. Ett REST-endepunkt tilsvarer sjelden nøyaktig ett GraphQL-felt, og flere REST-kall blir ofte til én spørring.

  3. Utforsk GraphQL-APIet. Bruk GraphiQL, som lar deg bla i skjemaet og få autofullføring mens du skriver. Åpne GraphiQL for testmiljøet eller GraphQL Voyager for produksjonsmiljøet for en visuell oversikt over typene (skjemaene i test og produksjon er normalt identiske).

    GraphQL-klienter henter normalt skjemaet ved å spørre serveren om det — det kalles introspeksjon. Vi har slått av introspeksjon i produksjonsmiljøet, så peker du IDE-en din dit, får du avslag. Bruk testmiljøet eller last ned skjemafilene i stedet. Se Introspeksjon for alternativene, og FS GraphQL API for URLer til skjema og endepunkt i hvert miljø.

    Deler av APIet er ikke på stabil kontrakt ennå. Felt på beta- eller eksperimentell kontrakt er skjult med mindre du sender Feature-Flags-headeren. Guidene merker hvert eksempel med hvilket kontraktsnivå det krever. Se Tidlig tilgang til funksjonalitet under utvikling.

  4. Kontakt fs-support@sikt.no hvis noe mangler. Små tilpasninger i GraphQL-APIet kan vi ofte gjøre raskt. Si gjerne hvilket gammelt endepunkt du erstatter — det gjør det lettere for oss å finne riktig felt.

  5. Implementer klienten mot GraphQL-APIet.

Du kan beholde API-brukeren din​

API-brukere som har tilgang til de gamle APIene, kan også brukes mot FS GraphQL API. Du bestiller tilgang til FS GraphQL API på vanlig måte, og det er viktig at du spesifiserer hvilke data du ønsker tilgang til. Brukte du et API uten autentisering, som FSWS-fskode, må du bestille en ny API-bruker. Les mer i Hvordan får jeg tilgang? og Tilgangsstyring med RAS.

Fire ting som fungerer annerledes enn i REST​

1. Ett endepunkt, alltid POST​

Der REST-APIet hadde én URL per ressurs, har FS GraphQL API én URL totalt. Alle spørringer og mutasjoner sendes som POST med et JSON-objekt som har feltene query og eventuelt variables. URLen er den samme enten du leser eller skriver. Eksemplet under bruker basic auth med API-brukeren din — du kan også autentisere med Feide, se Autentisering:

curl -X POST https://api.fellesstudentsystem.no/graphql/ \
  -u "brukernavn:passord" \
  -H "Content-Type: application/json" \
  -d '{"query":"query HentEmner($inst: String!) { emnerV2(filter: {eierOrganisasjonskode: $inst}, first: 2) { nodes { kode versjonskode } } }","variables":{"inst":"1234"}}'

eierOrganisasjonskode er lærestedets institusjonsnummer. De aller fleste spørringene i FS GraphQL API krever at du oppgir det, fordi dataene i FS eies av det enkelte lærestedet. På noen eldre, fortsatt gyldige spørringer heter argumentet eierInstitusjonsnummer i stedet — blant annet emnerGittEmnekoder. Verdien er den samme, bare navnet er forskjellig.

URLer for test- og demomiljøet finner du under Nyttige URLer.

2. Du ber om feltene du vil ha — og henter relaterte data i samme kall​

I REST bestemmer serveren hva et svar inneholder. I GraphQL velger du selv, og du får bare det du ber om. Du kan også følge relasjoner nedover i samme spørring (nøstede spørringer): der du før hentet et studieprogram og deretter kalte et nytt endepunkt for hvert emne, ber du nå om emnene som et underfelt av studieprogrammet i én forespørsel.

Konsekvensen for migreringen er at feltmappingen sjelden blir én-til-én. Sammenlign derfor dataene klienten trenger, ikke kallene den gjør.

3. Paginering er cursorbasert, ikke side- eller offsetbasert​

Lister i FS GraphQL API følger Relay-standarden. Det finnes ingen offset/limit og ingen page-teller. I stedet ber du om first antall treff, får en endCursor tilbake, og sender den som after i neste kall:

query HentEmner($after: String) {
  emnerV2(
    first: 2
    after: $after
    filter: { eierOrganisasjonskode: "1234" }
  ) {
    pageInfo {
      endCursor
      hasNextPage
    }
    nodes {
      kode
      versjonskode
    }
  }
}
{
  "data": {
    "emnerV2": {
      "pageInfo": {
        "endCursor": "MjA6MTIzNCwxNTAsRkxMLTM2NSwx",
        "hasNextPage": true
      },
      "nodes": [
        { "kode": "FAH342", "versjonskode": "1" },
        { "kode": "FLL-365", "versjonskode": "1" }
      ]
    }
  }
}

Du gjentar kallet med after: endCursor så lenge hasNextPage er true.

Sett alltid first selv

Utelater du first, brukes en standardverdi som varierer fra felt til felt. Det er uansett en hard grense på 1000 treff per side, uansett hva du ber om. En klient som antar «ingen grense betyr alle treff», får stille færre rader enn den venter. Paginering er dessuten forover-bare: last og before støttes ikke. Gjeldende grenseverdier finner du under Tekniske grenser for FS-API.

Full dokumentasjon: Spørringer – Paginering.

4. HTTP 200 betyr ikke at alt gikk bra​

REST-APIene svarte med 400, 404 eller 500 når noe feilet. GraphQL svarer normalt med HTTP 200 uansett, og legger feilene i svaret. En klient som bare sjekker statuskoden, vil tro at alt gikk bra. Det finnes to typer feil, og de håndteres forskjellig.

Feil på toppnivå ligger i errors ved siden av data i JSON-svaret. De betyr som regel at noe gikk galt på serversiden, eller at spørringen din er ugyldig:

{
  "errors": [
    {
      "message": "Internal Server Error(s) while executing query",
      "locations": []
    }
  ],
  "data": null
}

Feil på forretningsregler returneres av mutasjonene selv, i et errors-felt inne i svaret fra mutasjonen. Dette feltet er en union-type: du må bruke inline fragments (... on) for å velge hvilke felter du vil ha ut. Alle feiltypene implementerer grensesnittet Error, som alltid har message og path. Ber du om ... on Error, får du også med feiltyper vi legger til senere:

mutation EndreEpost {
  endreEpostadresserForPersonProfiler(
    input: [{ id: "NzY6MTIzNCwxNDQw", privatEpost: "ny.adresse@example.org" }]
  ) {
    personProfiler {
      id
    }
    errors {
      ... on Error {
        __typename
        message
        path
      }
    }
  }
}

Merk at errors { message } uten ... on er ugyldig GraphQL og blir avvist. Legg også merke til at input er en liste — de fleste mutasjonene tar imot flere rader i samme kall, der REST krevde ett kall per rad.

Full dokumentasjon: Mutasjoner – Generell og spesifikk feilhåndtering.

IDene er ikke nødvendigvis de samme​

FS GraphQL API bruker sine egne IDer. De er base64-enkodede tekststrenger, for eksempel NzY6MTIzNCwxNDQw. Behandle dem som ugjennomsiktige: du kan riktignok base64-dekode dem, men innholdet og formatet er en intern implementasjonsdetalj som kan endres uten varsel. Ikke konstruer dem selv, og ikke parse dem for å hente ut de gamle nøklene. Bruk dem kun slik du fikk dem.

Om en ID fra det gamle APIet kan brukes direkte mot FS GraphQL API, varierer fra API til API. For FS-APIet er IDene for eksempel forskjellige, slik at klienten må slå opp objektet i FS GraphQL API først. Sjekk guiden for ditt API — den sier hva som gjelder der. Står det ikke eksplisitt, spør fs-support@sikt.no før du antar noe. En feil antakelse her oppdages først i produksjon.

For enkelte entiteter tilbyr vi oppslag på de gamle nøklene, gjennom spørringer som semesterregistreringerGittLegacyIder. Du oppgir feltene som til sammen utgjorde IDen i den gamle tjenesten, og får tilbake objektet med den nye IDen. Et fullstendig eksempel — inkludert at du også må oppgi eierOrganisasjonskode — finner du i Fra FS-APIet til FS GraphQL API.

Legacy-oppslagene ligger på eksperimentell kontrakt

Alle …GittLegacyIder-spørringene er i dag kun tilgjengelige på eksperimentell kontrakt. Du må sende Feature-Flags: beta,experimental for å se dem, og API-kontrakten sier at eksperimentelt nivå kan endres uten forvarsel og ikke er ment å utvikles mot. Trenger du et av disse oppslagene i en integrasjon som skal i drift, kontakt fs-support@sikt.no og be om at kontraktsnivået heves til beta.

Gradvis overgang​

Du kan bruke REST/OpenAPI og GraphQL samtidig. Det er ofte en god strategi for å migrere en klient stegvis, og noen ganger nødvendig — for eksempel hvis et endepunkt du bruker avvikles før hele behovet ditt er løst i GraphQL-APIet.

Vi legger til rette for gradvis overgang ved å:

  1. Tilby spørringer og mutasjoner som tilsvarer REST/OpenAPI-endepunkter vi har varslet avvikling av
  2. Skrive migreringsguider med eksempler på hvordan du kan erstatte enkeltendepunkter med GraphQL
  3. Tilby oppslag på IDer fra de gamle APIene der det er hensiktsmessig, se IDene er ikke nødvendigvis de samme

Finner du ikke det du trenger?​

Kontakt fs-support@sikt.no. Beskriv gjerne hvilket gammelt endepunkt du erstatter og hvilke felt du er avhengig av — da finner vi raskere ut om funksjonaliteten finnes under et annet navn, om den ligger på et lavere kontraktsnivå, eller om vi må bygge den.

Vil du varsles om endringer i APIene, meld deg på e-postlista ved å sende e-post til fs-plattform-brukere-join@lister.sikt.no.