Gå til hovedinnhold

Introspeksjon i FS GraphQL API

Her forklarer vi hva GraphQL-introspeksjon er, hvorfor det er deaktivert i produksjonsmiljøet, og hvilke alternativer du har tilgjengelig.

Hva er GraphQL-introspeksjon?​

GraphQL-introspeksjon er en standardfunksjon som lar deg spørre APIet om dets eget skjema. I stedet for å lese dokumentasjon, kan du sende en introspeksjons-spørring som dette:

{
  __schema {
    types {
      name
      fields {
        name
        type {
          name
        }
      }
    }
  }
}

Denne spørringen returnerer hele skjemaet: alle typer, felt, argumenter og beskrivelser.

Introspeksjon er svært nyttig for utviklere som lager GraphQL-verktøy. For vanlige brukere av GraphQL er det forøvrig ikke noe man trenger å forholde seg til.

Hvorfor er introspeksjon nyttig?​

Gitt et GraphQL API som tilbyr introspeksjon, så er det nok å taste inn URL til APIet for å komme i gang. Verktøyet bruker introspeksjon for å hente informasjonen som trengs for å gi brukeren hjelp til å forstå og bruke APIet. For eksempel i form av:

  • Autofullføring i IDE: Din kodeeditor kan foreslå felt mens du skriver
  • Validering: Sjekke at spørringer er korrekte før de sendes
  • Typegenerering: Automatisk generere TypeScript/Java/Kotlin-typer fra skjema
  • Utforskning: Finne ut hva som er mulig uten å lese dokumentasjon
  • Visualisering: Automatisk tegning av diagrammer som viser hvordan dataene i APIet henger sammen

Verktøy som bruker introspeksjon:

  • GraphiQL (spørringseditor)
  • Apollo Client (kodegenerering)
  • GraphQL Playground
  • IDE-plugins (VS Code, IntelliJ, WebStorm)
  • Voyager (skjemavisualisering)

Hvordan bruker FS introspeksjon?​

Vår tilnærming​

MiljøIntrospeksjonBegrunnelse
Produksjon (https://api.fellesstudentsystem.no/graphql)❌ DeaktivertSkjemaet er stort, introspeksjon er ressurskrevende
Demo (https://api-test.fellesstudentsystem.no/graphql)✅ AktivertUnder pilot
Test (https://api-test.fsweb.no/graphql)✅ AktivertFor utvikling og testing

Hvorfor er introspeksjon deaktivert i produksjon?​

1. Performance​

Performance-hensyn

FS GraphQL API har et stort skjema med mange typer, felt og relasjoner. Introspeksjon av hele skjemaet er en ressurskrevende operasjon som kan påvirke responstiden for vanlige spørringer.

Produksjonsmiljøet skal primært være dedikert til produksjonstrafikk, ikke utforskning og utvikling.

2. Riktig utviklingspraksis​

Vi ønsker at utvikling og testing skal skje mot testmiljøet, ikke mot produksjon.

Dette gir bedre arbeidsflyt:

  • Test nye spørringer mot testmiljøet først
  • Oppdage problemer før de når produksjon
  • Unngå å påvirke produksjonsytelse under utvikling

3. Introspeksjon er ikke nødvendig i produksjon​

Når koden er testet og klar for produksjon, trenger du ikke lenger introspeksjon. Spørringer er allerede skrevet og validert.

Alternativer til introspeksjon i produksjon​

Avhengig av hva du ønsker å oppnå så tilbyr vi fire alternativer til introspeksjon mot produksjonsmiljøet vårt.

1. Apollo Studio Public Skjemaer​

Anbefalt alternativ

Apollo Studio er det godt verktøy for å utforske skjema, se endringer og teste spørringer visuelt.

Anbefalt for: Utforskning av skjema, se endringer, visuell forståelse

Tilgjengelig:

  • Både Prod og Test
  • Alle kontrakter (Stable, Beta, Experimental)
  • GraphOS Studio Explorer (med autentisering)
  • Endringer - se alle endringer mellom versjoner
  • Visuell skjema-utforskning

Fordeler:

  • Godt brukergrensesnitt
  • Endringsoversikt som viser hva som er endret
  • Alltid oppdatert
  • Ingen last på produksjonsmiljøet

Hvordan bruke:

  1. Gå til Apollo Studio
  2. Utforsk skjema visuelt
  3. Test spørringer i Explorer (krever autentisering)

2. Statiske skjema-filer​

Introspeksjon lar verktøy hente informasjon om GraphQL APIet ved å sende spørringer til GraphQL APIet. Fasiten bak denne informasjonen ligger forøvrig i skjemafilene våre. De fleste verktøy som støtter introspeksjon støtter også å bruke disse skjemafilene direkte.

Anbefalt for: Kodegenerering, IDE autofullføring, lokal utvikling

URL: https://fs.sikt.no/tjenester/api/graphql/

Tilgjengelig:

  • Alle varianter (Stable, Beta, Experimental)
  • Både Prod og Test
  • Nedlastbare .graphqls-filer

3. Testmiljø med introspeksjon​

Anbefalt for: Utvikling, testing av nye spørringer, live-utforskning

URL: api-test.fsweb.no/graphql

Bruk dette når:

  • Du vil teste nye spørringer
  • Du trenger autofullføring i live-miljø
  • Du vil bruke GraphiQL mot FS
Viktig

Testmiljøet har samme skjema som produksjon, så testing her er like relevant.

4. GraphQL Voyager​

Anbefalt for: Visuell forståelse av skjema, se relasjoner mellom typer

URL: fs.sikt.no/tjenester/api/graphql/

Funksjonalitet:

  • Interaktivt grafisk diagram av skjema
  • Se relasjoner mellom typer visuelt
  • Klikk deg gjennom skjema

Bruk dette når:

  • Du vil få oversikt over hele skjema
  • Du vil se hvordan typer henger sammen
  • Du vil forstå datamodellen visuelt

Sist oppdatert: 2026-03-11