Gå til hovedinnhold
Mål

Når du er ferdig med dette kapitlet skal du ha oversikt over hvordan du går fram for å lære deg det du trenger om GraphQL for å komme i gang med API-design.

Lær deg GraphQL

For å bli en god API-designer, trenger du å kunne litt om GraphQL-teknologien. Det er noen ting vi forutsetter at du har gjort, og noen begreper vi forutsetter at du kjenner til, før vi går videre.

Få tilgang til FS GraphQL API​

For å kunne gjøre en god jobb som API-designer, bør du ha mulighet til teste ut APIet direkte. Hvis du jobber for en av FS-institusjonene, eller en av deres underleverandører, se API-katalogen for hvordan du får tilgang. Jobber du i Sikt, kan du kontakte FS-support direkte hvis det ikke finnes noen på teamet ditt som kan gi deg tilgang.

Når du har fått tilgang til APIet, kan du teste spørringer og mutations mot APIet ved å følge denne veiledningen:

Nøkkelbegreper: Graf, noder, kanter, subtyper, løvfelter​

Vi trenger litt fagterminologi for å snakke om GraphQL-APIer. Begrepsbruken rundt GraphQL er ikke alltid helt konsistent, og de samme begrepene kan brukes i litt forskjellig betydning. I denne håndboka bruker vi følgende begreper når vi snakker om GraphQL-APIet:

  • Graf: En graf forstår vi her som et nettverk av sammenkoblede data
  • Node: En node er et punkt i grafen som inneholder opplysninger som hører naturlig sammen, og som det også gir mening for en klient å hente direkte. Eksempelvis er Emne en node i FS GraphQL API.
  • Kant: En kant er en kobling mellom to forskjellige noder. En kant vil alltid ha et navn, og en retning. For eksempel har StudentVedInstitusjon en kant mot ProgramStudierett. Kanten heter programStudieretter og returnerer alle studentens studieretter på studieprogrammer ved denne institusjonen.
  • Subtype: En subtype er i likhet med en node et punkt i grafen som inneholder opplysninger som hører sammen, og som tilhører foreldernoden men som ikke kan stå uavhengig av foreldernoden. Et emnes vekting tilhører for eksempel emnet og er meningsløst alene. Et emnes administrative organisasjonsenhet, på den annen side, klarer seg utmerket alene. Koblingen fra foreldrenoden til subtypen går via et navngitt felt, og subtypen vil også ha sitt eget navn, men vi velger her å reservere begrepet "kant" for koblinger mellom noder.
  • Løvfelt: Et løvfelt er et punkt i grafen som bare inneholder ett datafelt. Både noder og subtyper kan ha løvfelter.

Lær deg å bruke GraphQL Voyager for å utforske APIet​

I de neste kapitlene vil vi bruke GraphQL Voyager for å utforske hva som allerede er tilgjengelig i APIet. Du bruker API-brukeren din for å logge deg på:

I Voyager kan du navigere deg gjennom et kart over APIet, enten ved å klikke deg fra sted til sted, eller ved å bruke søkefunksjonaliteten.

Noder, kanter og løvfelter

I Voyager vil du se APIet som et nettverk av bokser og piler. Dette nettverket kalles en graf. Boksene i grafen, er enten noder eller subtyper. Hver node eller subtype har en liste med felter. Noen av feltene har en pil ut til en annen boks. Piler som ender i en node, kaller vi kanter. Piler som ender i en subtype er bare en kobling mellom foreldrenoden og subtypen. ![Oversiktsbilde over APIet i Voyager](/images/oversiktsbilde voyager.jpg)

Hvis du er kjent med FS fra før, vil du trolig kjenne igjen det du ser i Voyager, selv om navngivingen i noen tilfeller vil være litt forskjellig. Du kan lese mer om vurderingene vi har gjort om navngiving her: Designvalg.

Nabolag i Voyager

Prøv å klikke på en node eller subtype i Voyager og se hva som skjer. Da vil denne få fokus, men også alle andre noder og subtyper som er koblet til den. Det kan vi kalle nodens "nabolag" i grafen. Nabolaget til noden Studieprogram i Voyager

Wordpress har laget en enkel og oversiktlig guide til hvordan man navigerer i Voyager: GraphQL API for Wordpress: Intro to the Voyager client

Lær deg GraphQL-skjemaspråket​

De neste kapitlene forutsetter at du har en grunnleggende kjennskap til hvordan GraphQL-skjemaet er bygd opp, og at du kjenner de mest sentrale begrepene og konseptene. Du finner en lettfattelig og komplett oversikt over skjema-språket her: GraphQL.org: Schemas and types. Du velger selv om du vil lese denne før du går videre, eller om du vil bruke den som et oppslagsverk underveis. De neste kapitlene vil ha praktiske eksempler for alt vi skal gjøre, så begge deler vil fungere.

Her er det verdt å nevne at det finnes tilgjengelige nettkurs og tutorials som gir innføringer i GraphQL-skjemaspråket. Vi nevner ingen her, fordi vi ikke har sett på noen slike selv. Har du tips til et godt kurs eller en pedagogisk gjennomgang, er det bare å gi beskjed, så kan vi legge dem til her.