Gå til hovedinnhold

Fra FSWS-Institusjonsregisteret (fskode) til FS GraphQL API

⚠ Denne tjenesten avvikles etter 31. mars 2027. Nye integrasjoner bør bygges direkte på FS GraphQL API. Se Sikts avviklingspraksis og avviklingsloggen. Kilde: Teknisk dokumentasjon for FSWS-Institusjonsregisteret

FSWS-Institusjonsregisteret (også kalt FSWS-fskode) tilbyr oppslag av institusjonsdata gjennom to REST-endepunkter:

  • Henting av én institusjon gitt institusjonsnummer
  • Henting av en liste over institusjoner, med valgfri filtrering

Begge er erstattet av FS GraphQL API. Denne guiden viser hvert endepunkt side om side med spørringen som erstatter det. GraphQL lar deg selv velge hvilke felt du henter — bruk gjerne eksemplene som utgangspunkt og trim dem til ditt behov.

Finner du ikke det du trenger, kontakt fs-support@sikt.no.

Før du starter​

Sett deg inn i disse tingene før du går videre:

Tilgang: ingen egen RAS-rolle kreves​

FSWS-Institusjonsregisteret var åpent uten autentisering. FS GraphQL API krever at kallet er autentisert som en API-bruker, men datasettet i denne guiden har ingen egen navngitt RAS-rolle — det er ikke institusjonsspesifikt, så vanlig autentisert tilgang er nok. Se Hvordan får jeg tilgang? for å bestille en API-bruker.

Alle spørringene i denne guiden ligger på eksperimentell kontrakt​

organisasjoner, organisasjonerGittOrganisasjonskoder, organisasjonstyper og organisasjonstyperGittOrganisasjonstypekoder er i dag kun tilgjengelige på experimental kontraktsnivå. Du må sende headeren

{ "Feature-Flags": "experimental" }

for at de i det hele tatt skal finnes i skjemaet du spør mot. Uten headeren får du feilen FieldUndefined.

API-kontrakten sier at experimental-nivå kan endres eller fjernes uten forvarsel. Skal du bygge en produksjonsintegrasjon på disse spørringene, kontakt fs-support@sikt.no og be om at kontraktsnivået heves.

Av feltene i eksemplene under er kun disse stable: organisasjonskode, forkortelse, navnAlleSprak med underfeltene nb, nn, en og se, samt Land-feltene landnummer, landkodeAlfa3 og navnAlleSprak. Alt annet — url, erasmusInstitusjonskode, organisasjonstype, schacHomeOrganization, besoksadresse, kanMottaSemesteravgift, navnAlleSprakHistorikk, fskodeAkkreditering og selve land-feltet — er experimental. Merk at land er experimental selv om feltene inne i Land er stable: headeren må uansett settes.

Ikke forveksle Organisasjon med URegOrganisasjon​

Skjemaet har også en type URegOrganisasjon og spørringen uRegOrganisasjoner, fra Utdanningsregisteret. Den dekker et bredere organisasjonsbegrep (også forvaltningsorganer og leverandører), og id-verdiene der er ikke de samme som for Organisasjon, selv for samme institusjon. Det er Organisasjon som erstatter FSWS-Institusjonsregisteret.

IDer: institusjonsnr virker videre, men id er noe nytt​

institusjonsnr fra FSWS er den samme verdien som organisasjonskode i FS GraphQL API. Du kan bruke institusjonsnumrene du allerede har lagret, direkte som argument til organisasjonerGittOrganisasjonskoder og som organisasjonskode i responsen. Eneste forskjell er typen: FSWS returnerte institusjonsnr som tall (185), GraphQL bruker streng ("185").

id er derimot en ny identifikator uten motstykke i FSWS. Det er en base64-enkodet node-ID, for eksempel T3JnYW5pc2Fzam9uc3R5cGU6VU5JVg for organisasjonstypen UNIV. Behandle den som ugjennomsiktig: ikke konstruer den selv, og ikke parse den for å hente ut koden. Trenger du organisasjonskoden, spør etter organisasjonskode-feltet direkte i stedet.

Du trenger likevel node-IDer ett sted: filteret på organisasjoner tar node-IDer for Organisasjonstype, ikke rå typekoder — se Filtrer på organisasjonstype under.

Hent én institusjon​

FSWS-Institusjonsregisteret tillot oppslag av en institusjon gitt institusjonsnummer. I FS GraphQL API bruker du spørringen organisasjonerGittOrganisasjonskoder.

FSWS-Institusjonsregisteret:

GET /fskoder/institusjon/185

Eksempel på svar:

{
  "institusjonsnr": 185,
  "akronym": "UIO",
  "navnNb": "Universitetet i Oslo",
  "navnEn": "University of Oslo",
  "navnNn": "Universitetet i Oslo",
  "landNr": 0,
  "typeKode": "UNIV",
  "url": "http://www.uio.no",
  "erasmusInstKode": "N  OSLO01",
  "schacHomeOrganization": "uio.no",
  "navnHistList": []
}

FS GraphQL API:

query {
  organisasjonerGittOrganisasjonskoder(
    organisasjonskoder: ["185"]
  ) {
    organisasjonskode
    forkortelse
    navnAlleSprak {
      nb
      nn
      en
      se
    }
    url
    erasmusInstitusjonskode
    organisasjonstype {
      kode
      beskrivelseAlleSprak {
        nb
      }
    }
    land {
      landnummer
      landkodeAlfa3
      navnAlleSprak {
        nb
      }
    }
    schacHomeOrganization
  }
}

Eksempel på svar:

{
  "data": {
    "organisasjonerGittOrganisasjonskoder": [
      {
        "organisasjonskode": "185",
        "forkortelse": "UIO",
        "navnAlleSprak": {
          "nb": "Universitetet i Oslo",
          "nn": "Universitetet i Oslo",
          "en": "University of Oslo",
          "se": null
        },
        "url": "https://www.uio.no/",
        "erasmusInstitusjonskode": "N  OSLO01",
        "organisasjonstype": {
          "kode": "UNIV",
          "beskrivelseAlleSprak": {
            "nb": "Universitet som mottar statstilskudd"
          }
        },
        "land": {
          "landnummer": "0",
          "landkodeAlfa3": "NOR",
          "navnAlleSprak": {
            "nb": "Norge"
          }
        },
        "schacHomeOrganization": "uio.no"
      }
    ]
  }
}

Ukjent organisasjonskode gir ingen feil. FSWS-Institusjonsregisteret svarte 404 når institusjonsnummeret ikke fantes. organisasjonerGittOrganisasjonskoder returnerer i stedet en kortere liste — koden faller bare ut av resultatet, uten feilmelding. Sender du inn fem koder og får fire objekter tilbake, må du selv sammenligne organisasjonskode i svaret mot det du spurte om for å finne hvilken som manglet.

Nytt i FS GraphQL API​

Disse feltene fantes ikke i FSWS-Institusjonsregisteret:

Felt uten motpart i FSWS-Institusjonsregisteret
FS GraphQL API-feltHva det er
navnAlleSprak { se }Nord-samisk navn
organisasjonstype { beskrivelseAlleSprak { nb nn en } }Beskrivelse av organisasjonstypen, ikke bare koden
besoksadresse { co gate postnummerOgSted land }Organisasjonens fysiske besøksadresse
kanMottaSemesteravgiftOm organisasjonen er godkjent betalingsmottaker for semesteravgift. Finnes også som filter på organisasjoner
fskodeAkkreditering { erAkkreditert periode { fraArstall tilArstall } kilde }Akkrediteringsstatus og -periode. Ikke bekreftet at dette fantes i FSWS sin faktiske respons — verifiser med tjenesteeier før du forutsetter at dette er nytt data, ikke en migrert verdi
land { landkodeAlfa3 navnAlleSprak { nb nn en } }Landet som eget objekt, ikke bare landnummer

FSWS returnerte navnHistList som én flat liste med alle historiske navn. I GraphQL er dette en Connection med first: Int = 100 som standard. For organisasjoner med mange navneendringer må du sjekke pageInfo.hasNextPage og hente flere sider:

query {
  organisasjonerGittOrganisasjonskoder(organisasjonskoder: ["185"]) {
    navnAlleSprakHistorikk(first: 100) {
      nodes {
        und
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Hent liste over institusjoner​

FSWS-Institusjonsregisteret tillot filtrering av institusjoner på type (institusjonstypekode) og endringerSiden (timestamp). I FS GraphQL API bruker du spørringen organisasjoner.

Viktige forskjeller:

  • FS GraphQL API bruker cursor-basert paginering i stedet for å returnere alle resultater i én liste
  • Filteret type erstattes av organisasjonstyper, som tar en liste av node-IDer, ikke rå typekoder
  • Filteret endringerSiden erstattes av endretEtter — se merknaden under
  • Standard sidestørrelse er 100 elementer per side
  • Resultatet er sortert stigende på organisasjonskode (keyset-paginering) — du kan trygt bla gjennom alle sidene uten å hoppe over eller gjenta rader

FSWS-Institusjonsregisteret (alle institusjoner):

GET /fskoder/institusjoner

FS GraphQL API (alle organisasjoner med paginering):

query {
  organisasjoner(first: 100) {
    nodes {
      organisasjonskode
      forkortelse
      navnAlleSprak {
        nb
        en
      }
      url
      organisasjonstype {
        kode
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Eksempel på svar:

{
  "data": {
    "organisasjoner": {
      "nodes": [
        {
          "organisasjonskode": "184",
          "forkortelse": "UIB",
          "navnAlleSprak": {
            "nb": "Universitetet i Bergen",
            "en": "University of Bergen"
          },
          "url": "https://www.uib.no/",
          "organisasjonstype": { "kode": "UNIV" }
        },
        {
          "organisasjonskode": "185",
          "forkortelse": "UIO",
          "navnAlleSprak": {
            "nb": "Universitetet i Oslo",
            "en": "University of Oslo"
          },
          "url": "https://www.uio.no/",
          "organisasjonstype": { "kode": "UNIV" }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "WzE4NV0"
      },
      "totalCount": 28833
    }
  }
}

Registeret inneholder også utenlandske institusjoner, så det totale antallet er langt høyere enn antallet norske læresteder. Filtrer på organisasjonstyper eller endretEtter der du kan, i stedet for å hente alt.

For å hente neste side, bruk after-parameteren med endCursor-verdien:

query {
  organisasjoner(first: 100, after: "WzE4NV0") {
    nodes {
      organisasjonskode
      forkortelse
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Filtrer på organisasjonstype​

Filteret organisasjonstyper tar node-IDer for Organisasjonstype, ikke rå typekoder som "UNIV". Slå opp node-IDen for en gitt typekode med organisasjonstyperGittOrganisasjonstypekoder:

query {
  organisasjonstyperGittOrganisasjonstypekoder(
    organisasjonstypekoder: ["UNIV"]
  ) {
    id
    kode
    beskrivelseAlleSprak {
      nb
    }
  }
}

Eksempel på svar:

{
  "data": {
    "organisasjonstyperGittOrganisasjonstypekoder": [
      {
        "id": "T3JnYW5pc2Fzam9uc3R5cGU6VU5JVg",
        "kode": "UNIV",
        "beskrivelseAlleSprak": {
          "nb": "Universitet som mottar statstilskudd"
        }
      }
    ]
  }
}

Bruk deretter den returnerte id-verdien som filter:

query {
  organisasjoner(
    first: 100,
    filter: {
      organisasjonstyper: ["T3JnYW5pc2Fzam9uc3R5cGU6VU5JVg"]
    }
  ) {
    nodes {
      organisasjonskode
      forkortelse
      organisasjonstype {
        kode
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Du kan også liste alle tilgjengelige organisasjonstyper med organisasjonstyper:

query {
  organisasjonstyper(first: 100) {
    nodes {
      id
      kode
      beskrivelseAlleSprak {
        nb
      }
    }
  }
}

endretEtter oppfører seg ikke som endringerSiden​

FSWS-Institusjonsregisteret (endringer siden timestamp):

GET /fskoder/institusjoner?endringerSiden=1709913600000

FS GraphQL API (endringer etter tidspunkt):

query {
  organisasjoner(
    first: 100,
    filter: {
      endretEtter: "2024-03-08T16:00:00Z"
    }
  ) {
    nodes {
      organisasjonskode
      forkortelse
    }
  }
}

Det er tre forskjeller, og den siste kan gi deg duplikater hvis du ikke tar høyde for den:

  1. Verdien er en DateTime i ISO 8601-format, ikke millisekunder siden epoke.
  2. Klokkeslettet forkastes. Filteret sammenligner mot endringsdato, ikke tidspunkt — 2024-03-08T16:00:00Z og 2024-03-08T00:00:00Z gir nøyaktig samme resultat.
  3. Sammenligningen er «på eller etter», ikke «etter», til tross for navnet. Sender du inn datoen for forrige synkronisering, får du hele det døgnets endringer på nytt. Kjører du inkrementell synkronisering, må klienten enten deduplisere mot det den allerede har, eller spørre fra dagen etter forrige kjøring og akseptere at endringer samme dag kommer med først neste gang.

Filteret skal på sikt erstattes med mer finkornede hendelsesspørringer som gir bedre kontroll på hva som faktisk er endret.

Feltmapping​

Feltmapping fra FSWS-Institusjonsregisteret til FS GraphQL API
FSWS-Institusjonsregisteret (JSON-felt)FS GraphQL API (felt)KontraktsnivåMerknad
institusjonsnrorganisasjonskodestableSamme verdi, streng i stedet for tall
akronymforkortelsestable
navnNbnavnAlleSprak { nb }stable
navnEnnavnAlleSprak { en }stable
navnNnnavnAlleSprak { nn }stable
typeKodeorganisasjonstype { kode }experimental
urlurlexperimental
erasmusInstKodeerasmusInstitusjonskodeexperimental
landNrland { landnummer }experimental (feltet), stable (underfeltene)
schacHomeOrganizationschacHomeOrganizationexperimental
navnHistListnavnAlleSprakHistorikk { nodes { und } }experimentalNå paginert, se over

Kontakt oss for hjelp ved behov​

Kontakt fs-support@sikt.no dersom du trenger hjelp til å komme i gang, eller underveis i migreringen. Beskriv gjerne hvilket FSWS-endepunkt du erstatter og hvilke felt du er avhengig av.