Gå til hovedinnhold

FS API-kontrakt og forvaltningsmodell for FS-APIene

På denne siden beskriver Sikt vilkårene for bruk av FS-APIene og hvordan Sikt forvalter dem. Her finner du Sikts forpliktelser som leverandør, dine plikter som konsument, og hvordan endringer varsles og håndteres. Enhver bruk av FS-APIene innebærer aksept av vilkårene i API-kontrakten.

Versjon: 1.1 · Sist oppdatert: 14.07.2026

Alle APIene i FS-tjenestekatalogen har en angitt livssyklus-fase og stabilitetsnivå i henhold til forvaltningsmodellen for FS-APIene. Merk at enkelte deler av et API kan ha et stabilitetsnivå som avviker fra det som er angitt for APIet som helhet. Sikt markerer tydelig i dokumentasjonen hvilke deler av APIet som har et avvikende stabilitetsnivå.

Generelle vilkår og servicenivå​

API-kontrakten er et tillegg til Sikts generelle avtalevilkår, som gjelder for alle Sikts leveranser. Der et forhold er særskilt regulert i API-kontrakten, går API-kontrakten foran de generelle avtalevilkårene.

FS-APIene leveres på Sikts servicenivå 1A, som beskriver responstider for support, varsling ved feil og planlagt vedlikehold, samt kontaktpunkt for kritiske feil og andre henvendelser.

FS API-kontrakt​

1: Sikts forpliktelser som leverandør​

Sikt forplikter seg til å:

  • levere maskinlesbar API-dokumentasjon og/eller tilsvarende teknisk dokumentasjon for all funksjonalitet i APIet.
  • varsle avvikling av felt og typer i FS GraphQL API maskinlesbart med @deprecated-direktiv og utfasingsdato, slik at du kan oppdage dette i dine verktøy.
  • varsle om ikke-bakoverkompatible endringer i våre etablerte varslingskanaler og i henhold til varslingsfristen for det aktuelle stabilitetsnivået
  • publisere en endringslogg som beskriver hva som er endret mellom versjoner.
  • gjøre testmiljø tilgjengelig slik at du kan verifisere integrasjoner før produksjonssetting av større endringer.

Tekniske rammer for spørringer​

For at APIet skal være stabilt for alle konsumenter, gjelder noen tekniske rammer for hvor mye en enkelt spørring kan be om:

  • Tidsgrense per spørring (timeout): En spørring som bruker lengre tid enn den fastsatte grensen, avbrytes automatisk. Det hindrer at enkelttunge spørringer låser ressurser for andre.
  • Sidestørrelse (paginering): Store resultatsett leveres side for side i stedet for alt på én gang. Oppgir du ikke noe, får du et standard antall treff per side, og du kan be om flere opp til et maksimum. Trenger du hele datasettet, henter du én side om gangen.

De til enhver tid gjeldende verdiene står i Tekniske grenser for FS-APIene

Nye eller endrede grenser som påvirker etablert bruk, varsler Sikt gjennom de vanlige varslingskanalene før de tas i bruk. Endringer i de tekniske grensene følger samme frister som ikke-bakoverkompatible endringer på det aktuelle stabilitetsnivået. Sikt kan allikevel sette inn akutte tiltak uten forhåndsvarsel for å verne driften, se Automatisk tilgangsbegrensning og Umiddelbar stenging.

2: Konsumentens forpliktelser​

Som konsument av FS-APIene forplikter du deg til å:

  • beskytte tilgangsnøkler og hemmeligheter. API-nøkler og OAuth-klienter skal ikke deles med uvedkommende, lagres ukryptert eller eksponeres i kildekode som er offentlig tilgjengelig.
  • holde integrasjonen oppdatert. Du er ansvarlig for å følge med på varslinger og tilpasse integrasjonen din til nye versjoner innen de fristene som gjelder for det aktuelle stabilitetsnivået.
  • gjøre deg kjent med forvaltningsmodellen for FS-APIene.
  • lovlig og forsvarlig bruk. Du skal kun bruke APIet til lovlige formål og i tråd med gjeldende regelverk, herunder personopplysningsloven og GDPR.
  • varsle Sikt ved uventet oppførsel. Dersom du oppdager feil, sikkerhetssvakheter eller uventet oppførsel i APIet, skal du melde fra til Sikt så snart som mulig.
  • bruke APIet hensynsfullt. Be kun om feltene du trenger, bruk paginering, mellomlagre svar der det er mulig, unngå aggressiv polling, og bruk eksponentiell backoff ved feil. [Bruk den tiltenkte mekanismen for masseuttak.], og unngå store, hyppige eller komplekse spørringer som kan påvirke ytelsen for andre brukere.
  • meld fra ved avvikling. Når du avvikler en integrasjon, skal du gi Sikt beskjed slik at vi kan rydde opp i tilganger.

3: Brudd på API-kontrakten​

Sikt vil tilstrebe dialog før tilgang begrenses eller trekkes tilbake. Det finnes likevel situasjoner der Sikt må handle raskt uten forhåndsvarsel.

Automatisk tilgangsbegrensning​

For å sikre stabil drift for alle konsumenter kan Sikt innføre automatisk begrensning av tilgang for klienter som overskrider fastsatte grenser for spørringshyppighet eller -volum. Slik begrensning skjer uten forhåndsvarsel og er midlertidig. Tilgangen gjenopprettes automatisk etter en fastsatt periode.

Dersom integrasjonen din treffes av automatisk begrensning gjentatte ganger, bør du gjennomgå spørremønsteret ditt i lys av retningslinjene for hensynsfull bruk i kapittel 2. Ta kontakt med kontakt@sikt.no dersom du er usikker på årsaken.

Umiddelbar stenging uten forhåndsvarsel​

I følgende situasjoner kan Sikt stenge tilgangen din umiddelbart:

  • det foreligger en sikkerhetsrisiko, for eksempel ved mistanke om at en klient eller tilgangsnøkkel er kompromittert,
  • bruken din utgjør en umiddelbar trussel mot driftsstabiliteten for andre konsumenter, eller
  • bruken din er i strid med gjeldende regelverk.

I slike tilfeller varsler Sikt deg så snart det er praktisk mulig.

Ved øvrige brudd​

Dersom Sikt avdekker at du bruker APIet i strid med denne API-kontrakten, vil Sikt normalt:

  • gi deg beskjed og be om at forholdet rettes,
  • midlertidig begrense eller stenge tilgangen din inntil forholdet er avklart, og
  • permanent tilbakekalle din API-tilgang ved alvorlige eller gjentatte brudd.

4: Varsling om endringer i FS-APIene og API-kontrakten​

Hold deg oppdatert om endringer og informasjon om FS-APIene og api-kontrakten gjennom å følge med i varslingskanalene under og gjøre deg kjent med stabilitetsnivåene i forvaltningsmodellen.

Varslingskanaler​

Sikt varsler om endringer i API-kontrakten og APIene gjennom følgende kanaler:

  • endringslogg, oppdateres ved hver versjon av API-kontrakten og ved større endringer i katalogen.
  • e-post til fs-plattformbrukere@sikt.no
  • avvikling av felt og typer merkes i tillegg maskinlesbart med @deprecated

Registrer deg for å motta varsler​

Gå til API-katalogen og meld deg på e-postlisten fs-plattformbrukere@sikt.no. Send en e-post til kontakt@sikt.no dersom du er usikker på om du er registrert.

For læresteder som er FS-kunder sender vi i tillegg varslinger om endringer i kontrakten, større API-endringer og avviklinger til postmottak og fs-kontakter.

Forvaltningsmodell for FS-APIene (governance)​

Forvaltningsmodellen beskriver formålet med de ulike stabilitetsnivåene og hvordan FS-APIene forvaltes gjennom hele levetiden sin.

Stabilitetsnivåer i API-kontrakten​

Stabilt nivå​

  • Vi leverer all funksjonalitet som er beskrevet i maskinlesbar API-dokumentasjon og/eller tilsvarende teknisk dokumentasjon til og med neste hovedversjon av API-katalogen.
  • Ikke-bakoverkompatible endringer (endringer som kan bryte eksisterende integrasjoner) gjøres bare i forbindelse med produksjonssetting av ny hovedversjon av API-katalogen.
  • Vi spesifiserer og bygger bakoverkompatible endringer fortløpende og lanserer dem så fort de er ferdige.
  • Vi gjør bare ikke-bakoverkompatible endringer dersom vi varslet dem før produksjonssetting av forrige hovedversjon av API-katalogen.
  • Vi kan varsle ikke-bakoverkompatible endringer når som helst i løpet av en hovedversjon.

Beta-nivå​

  • Vi leverer maskinlesbar API-dokumentasjon og/eller tilsvarende teknisk dokumentasjon for all funksjonalitet i APIet.
  • APIet kan inneholde kjente og ukjente feil.
  • Vi spesifiserer og bygger alle endringer fortløpende og lanserer dem så fort de er ferdige.
  • Vi varsler ikke-bakoverkompatible endringer minimum 2 uker før produksjonssetting.

Eksperimentelt nivå​

  • Det kan eksistere maskinlesbar API-dokumentasjon og/eller tilsvarende teknisk dokumentasjon for hele eller deler av APIet.
  • APIet kan inneholde kjente og ukjente feil.
  • Vi spesifiserer og bygger alle endringer fortløpende og lanserer dem så fort de er ferdige.
  • Vi kan produksjonssette ikke-bakoverkompatible endringer uten forvarsel.
Legg merke til at eksperimentelt nivå åpner for ikke-bakoverkompatible endringer uten varsel. Poenget med dette nivået er at det lar oss publisere forslag til skjemadesign som vi kan diskutere med deg og endre fortløpende etterhvert som vi lærer.

Det er ikke tenkt at du skal utvikle mot API på dette nivået. Dersom du har behov for funksjonalitet som ligger på eksperimentelt nivå, må du ta kontakt og be oss om å heve stabilitetsnivå for funksjonaliteten til beta.

Heve stabilitetsnivå​

  • Ny funksjonalitet blir normalt først lagt ut i test- og produksjonsmiljøene på eksperimentelt nivå. Her kan du utforske funksjonaliteten og vurdere om du ønsker å ta den i bruk.
  • Du kan be om at funksjonaliteten gjøres tilgjengelig på beta-nivå. Vi ønsker da at du gir oss mer informasjon om hvilket behov du vil løse med den gitte funksjonaliteten. Vi vurderer om funksjonaliteten er klar for å løftes, og gjør eventuelt nødvendige endringer. I beta-test-perioden kan vi gjøre endringer i APIet i samarbeid med deg.
  • Når du er fornøyd med beta-testen, kan du be om at funksjonaliteten løftes til stabilt nivå. Vi vurderer da igjen om funksjonaliteten er klar for å løftes, og gjør eventuelt nødvendige endringer.