Kom i gang

Her finner du informasjon du som konsument trenger for å komme i gang med å bruke GraphQL. I denne veilederen kommer vi til å bruke eksempel fra FS GraphQL API. Vi antar at du har fått tilgang til APIet og til test-miljøet. Hvis du ikke har det kan du lese om hvordan du får tilgang her.

Dersom du ønsker å se en visualisering av GraphQL-skjemaet kan du åpne GraphQL Voyager i testmiljøet.

Sett headere for eksperimentell og beta-funksjonalitet

Eksemplene under er foreløpig ikke tilgjengelig på stabil kontrakt. Du må derfor sette følgende i header når du gjør spørringen:

{ "Feature-Flags": "beta,experimental" }

Du kan lese mer om dette her: Tidlig tilgang til funksjonalitet under utvikling

Din første spørring

Vi vil ta utgangspunkt i følgende utfordring:

• Vi ønsker å hente informasjon om en person fra FS der vi kjenner fødselsnummeret.
• Vi vil hente ut navn og adresse, samt den interne ID'en til personprofilen i APIet.
• ID'en vil vi bruke senere.

For å gjøre din første spørring kan du bruke verktøyet GraphiQL. Dette er en brukervennlig GraphQL-klient med en god editor med auto-fullføring for GraphQL. Den viser relevant dokumentasjon om typene og feltene og har god søkefunksjonalitet for å finne frem i skjemaet. Følg denne lenken for å åpne GraphiQL for test-miljøet i FS GraphQP API.

Det finnes to måter å skrive spørringer på i GraphiQL. Hvis du er komfortabel med spørrespråket, kan du skrive spørringen direkte inn i skriveområdet. Hvis du trenger litt mer hjelp, kan du åpne GraphiQL Explorer ved å klikke på det uthevede ikonet i venstre-menyen:

Vi starter med å gi spørringen et passende navn. Deretter oppgir vi hvordan vi ønsker å filtrere søket. Foreløpig er det obligatorisk å oppgi eierinstitusjonsnummer. Hver FS-institusjon har et unikt nummer som ligger i denne lista: FS-virksomheter med kontaktpersoner. Hver bruker har tilgang til én institusjon, så pass på at du oppgir institusjonsnummeret til "din" institusjon, ellers vil du ikke få treff på spørringen din.

info

Hvis du bruker APIet i testmiljøet, tester du normalt mot en FS-demobase. I så fall må du passe på at du har lov til å bruke personopplysningene til testformål, siden disse databasene inneholder kopier av produksjonsdata. Det kan være lurt å opprette en fiktiv person til formålet, eller du kan bruke en anonymisert testpersonfra denne lista: Testpersoner i FS-demobaser.

I GraphQL må du eksplisitt gi beskjed om hvilke data du ønsker tilbake. I GraphiQL Explorer kan du gjøre dette ved å krysse av for feltene du ønsker data for.

Vi ender da med følgende spørring:

query MinForsteSporring {
  personProfilerGittFodselsnumre(
    fodselsnumre: "24547990443"
    eierInstitusjonsnummer: "1234"
  ) {
    id
    navn {
      fornavn
      etternavn
    }
    folkeregistrertAdresse {
      co
      gate
      postnummerOgSted
      land
    }
  }
}

Trykk på den rosa play-knappen i GraphiQL eller tast Ctrl + Enter for å kjøre spørringen:

Responsen skal se ut omtrent som dette:

{
  "data": {
    "personProfilerGittFodselsnumre": [
      {
        "id": "NzY6MTIzNCwxNDQw",
        "navn": {
          "fornavn": "Astrid",
          "etternavn": "Aga"
        },
        "folkeregistrertAdresse": {
          "co": "c/o Regina Aba",
          "gate": "August Cappelens gate 101",
          "postnummerOgSted": "0318 OSLO",
          "land": ""
        }
      }
    ]
  }
}

Din første mutasjon

Mutasjoner i GraphQL er operasjoner som endrer på data i systemet. Både oppretting av nye oppføringer og endring og sletting av eksisterende oppføringer kalles mutasjoner. I det følgende eksempelet skal vi endre folkeregistrert adresse for personen vi hentet tidligere.

Trykk på plusstegnet øverst til høyre i GraphiQL for å åpne en ny fane:

I den nye spørringen velger du mutasjonen endrePersonProfilFolkeregistrertAdresse. Her ser vi at det er en del obligatoriske felter som må fylles ut.

ID-feltet tar inn en personprofil-ID. Vi bruker den vi hentet med spørringen i forrige eksempel. De andre feltene fyller vi ut med dataene vi ønsker å oppdatere systemet med. Merk at det her ikke er nødvendig å oppgi eierinstitusjon, da denne blir utledet av IDen. NB! Tom verdi blanker ut eksisterende verdier.

Også i GraphQL-mutasjoner må velge hvilke data du vil ha tilbake. Denne mutasjonen tilbyr å returnere en PersonProfil (siden det er dette objektet som endres). Her er det naturlig å velge inn feltene i folkeregistrertAdresse, for å få den oppdaterte tilstanden tilbake. For eksempelets skyld tar vi også med oss fornavn og etternavn her.

Vi ender da med følgende mutasjon:

mutation MinForsteMutasjon {
  endreFolkeregistrerteAdresser(
    input: {
      id: "NzY6MTIzNCwxNDQw"
      co: ""
      gate: "Tokkebyen 46"
      postnummerOgSted: "5550 Sveio"
      land: ""
    }
  ) {
    personProfil {
      fornavn
      etternavn
      folkeregistrertAdresse {
        co
        gate
        postnummerOgSted
        land
      }
    }
  }
}

Og vi forventer følgende respons:

{
  "data": {
    "endrePersonProfilFolkeregistrertAdresse": {
      "personProfil": {
        "fornavn": "Astrid",
        "etternavn": "Aga",
        "folkeregistrertAdresse": {
          "co": null,
          "gate": "Tokkebyen 46",
          "postnummerOgSted": "5550 Sveio",
          "land": null
        }
      }
    }
  }
}

Som vi ser ble adressen endret som bestilt.

Hvis du jobber mot testdata som brukes av flere brukere er det lurt (og høflig) å rydde opp etter seg ved å endre dataene tilbake til det de var før du begynte å teste:

mutation MinForsteMutation {
  endrePersonProfilFolkeregistrertAdresse(
    input: {
      co: "c/o Regina Aba"
      gate: "August Cappelens gate 101"
      postnummerOgSted: "0318 Oslo"
      land: ""
    }
    id: "NzY6MTIzNCwxNDQw"
  ) {
    personProfil {
      fornavn
      etternavn
      folkeregistrertAdresse {
        co
        gate
        postnummerOgSted
        land
      }
    }
  }
}