Fra FSWS-fskoder (institusjonsregisteret) til FS GraphQL API

FSWS-fskode er under utfasing, og deler av tjenesten er nå erstattet av FS GraphQL API. Fskode-tjenesten består av to endepunkter for oppslag av institusjonsdata fra FSKODER-databasen:

Henting av en enkelt institusjon gitt institusjonsnummer
Henting av en liste over institusjoner med valgfri filtrering

Under gir vi eksempler for hvert enkelt endepunkt. GraphQL gir imidlertid stor fleksibilitet når det gjelder hvordan du henter dataene. Vi anbefaler at du bruker tid på å sette sammen spørringer som passer ditt behov.

Autentisering

FSWS-fskoder var tilgjengelig uten autentisering. FS GraphQL API krever derimot at du har en API-bruker. Siden dette APIet ikke er institusjonsspesifikt, kan tilgang bestilles direkte ved å kontakte kontakt@sikt.no.

Les mer om tilgang og autentisering:

Feltkartlegging

FSWS-fskode (JSON-felt)	FS GraphQL API (felt)	Merknad
`institusjonsnr`	`organisasjonskode`	Samme verdi, men feltet heter nå `organisasjonskode`
`akronym`	`forkortelse`
`navnNb`	`navnAlleSprak \{ nb \}`	Nøstet i flerspråklig objekt
`navnEn`	`navnAlleSprak \{ en \}`	Nøstet i flerspråklig objekt
`navnNn`	`navnAlleSprak \{ nn \}`	Nøstet i flerspråklig objekt
(ikke tilgjengelig)	`navnAlleSprak \{ se \}`	Nord-samisk navn er nytt i GraphQL
`typeKode`	`organisasjonstype \{ kode \}`	Nøstet objekt med beskrivelser
`url`	`url`
`erasmusInstKode`	`erasmusInstitusjonskode`
`landNr`	`land \{ landnummer \}`	Nøstet i Land-objekt med tilgang til landkoder og navn
`schacHomeOrganization`	`schacHomeOrganization`
`navnHistList`	`navnAlleSprakHistorikk \{ edges \{ node \{ und \} \} \}`	Liste over historiske navn (paginert)
`statusAkkreditert`	`fskodeAkkreditering \{ erAkkreditert \}`	Nøstet i akkrediteringsobjekt
`aarstallAkkreditertFra`	`fskodeAkkreditering \{ periode \{ fraArstall \} \}`
`aarstallAkkreditertTil`	`fskodeAkkreditering \{ periode \{ tilArstall \} \}`
`kildeAkkreditert`	`fskodeAkkreditering \{ kilde \}`

GET /fskoder/institusjon/{id} - Hent en enkelt institusjon

FSWS-fskode tillot oppslag av en institusjon gitt institusjonsnummer. I FS GraphQL API erstattes dette av spørringen organisasjonerGittOrganisasjonskoder.

Viktige forskjeller:

FSWS-fskode bruker institusjonsnummer som path-parameter, FS GraphQL API tar en liste av organisasjonskoder som argument
Organisasjonskode er av type String i GraphQL (ikke Integer)
Du velger selv hvilke felt du ønsker i responsen

FSWS-fskode:

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
    fskodeAkkreditering {
      erAkkreditert
      periode {
        fraArstall
        tilArstall
      }
      kilde
    }
    navnAlleSprakHistorikk {
      edges {
        node {
          und
        }
      }
    }
  }
}

Eksempel på svar:

{
  "data": {
    "organisasjonerGittOrganisasjonskoder": [
      {
        "organisasjonskode": "185",
        "forkortelse": "UIO",
        "navnAlleSprak": {
          "nb": "Universitetet i Oslo",
          "nn": null,
          "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",
        "fskodeAkkreditering": null,
        "navnAlleSprakHistorikk": {
          "edges": []
        }
      }
    ]
  }
}

Merk: GraphQL-spørringen gir deg i tillegg tilgang til organisasjonstype med beskrivelser og besøksadresse, som ikke var tilgjengelig via FSWS-fskode.

GET /fskoder/institusjoner - Hent liste over institusjoner

FSWS-fskode tillot filtrering av institusjoner på type (institusjonstypekode) og endringerSiden (timestamp). I FS GraphQL API erstattes dette av 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 Organisasjonstype-IDer (node-IDer)
Filteret endringerSiden erstattes av endretEtter, som tar en DateTime-verdi (ISO 8601-format)
Standard sidestørrelse er 100 elementer per side

FSWS-fskode (alle institusjoner):

GET /fskoder/institusjoner

FS GraphQL API (alle organisasjoner med paginering):

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

Eksempel på svar:

{
  "data": {
    "organisasjoner": {
      "edges": [
        {
          "node": {
            "organisasjonskode": "184",
            "forkortelse": "UIB",
            "navnAlleSprak": {
              "nb": "Universitetet i Bergen",
              "en": "University of Bergen"
            },
            "url": "https://www.uib.no/",
            "organisasjonstype": {
              "kode": "UNIV"
            }
          }
        },
        {
          "node": {
            "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
    }
  }
}

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

query {
  organisasjoner(first: 100, after: "WzE4NV0") {
    edges {
      node {
        organisasjonskode
        forkortelse
        navnAlleSprak {
          nb
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

FSWS-fskode (filtrert på type):

GET /fskoder/institusjoner?type=UNIV

FS GraphQL API (filtrert på organisasjonstype):

Filteret organisasjonstyper tar node-IDer for Organisasjonstype, ikke rå typekoder som "UNIV". Du kan 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"]
    }
  ) {
    edges {
      node {
        organisasjonskode
        forkortelse
        navnAlleSprak {
          nb
        }
        organisasjonstype {
          kode
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Eksempel på svar:

{
  "data": {
    "organisasjoner": {
      "edges": [
        {
          "node": {
            "organisasjonskode": "184",
            "forkortelse": "UIB",
            "navnAlleSprak": {
              "nb": "Universitetet i Bergen"
            },
            "organisasjonstype": {
              "kode": "UNIV"
            }
          }
        },
        {
          "node": {
            "organisasjonskode": "185",
            "forkortelse": "UIO",
            "navnAlleSprak": {
              "nb": "Universitetet i Oslo"
            },
            "organisasjonstype": {
              "kode": "UNIV"
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "WzE4NV0"
      }
    }
  }
}

Du kan også liste alle tilgjengelige organisasjonstyper med organisasjonstyper:

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

FSWS-fskode (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"
    }
  ) {
    edges {
      node {
        organisasjonskode
        forkortelse
        navnAlleSprak {
          nb
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Merk: endretEtter tar en DateTime i ISO 8601-format (ikke millisekunder som i FSWS-fskode). Filteret sammenligner mot endringsdato (kun dato, ikke klokkeslett). Dette filteret skal på sikt erstattes med mer finkornete hendelsesspørringer.

Kontakt oss for hjelp ved behov

Kontakt kontakt@sikt.no dersom du trenger hjelp til å komme i gang, eller underveis i migreringen.

Autentisering​

Feltkartlegging​

GET /fskoder/institusjon/{id} - Hent en enkelt institusjon​

GET /fskoder/institusjoner - Hent liste over institusjoner​

Kontakt oss for hjelp ved behov​

Autentisering

Feltkartlegging

GET /fskoder/institusjon/{id} - Hent en enkelt institusjon

GET /fskoder/institusjoner - Hent liste over institusjoner

Kontakt oss for hjelp ved behov