Mutasjoner

Skriveoperasjoner i GraphQL kalles mutasjoner. I motsetning til spørringer, så vil med andre ord en mutasjon endre på tilstanden til systemet.

Mutasjonene finnes som felter i Mutation-typen i GraphQL-skjemaet. De er navngitt etter hvilken operasjon som skal utføres og hvilke objekter som blir påvirket. For eksempel har vi en mutasjon som heter endreFolkeregistrerteAdresser, som endrer folkeregistrert adresse for en liste av person-profiler:

mutation SettFolkeregistertAdresser {
  endreFolkeregistrerteAdresser(
    input: [
      {id: "NzY6MTIzNCw4ODE", co: "c/o en god venn av meg", gate: "Gågata 3", postnummerOgSted: "0123 Oslo", land: "Norge"},
      {id: "NzY6MTIzNCw4ODI", co: "c/o en god venn av deg", gate: "Gågata 4b", postnummerOgSted: "0123 Oslo", land: "Norge"}
    ]
  ) {
    personProfiler {
      id
      folkeregistrertAdresse {
        co
        gate
        land
        postnummerOgSted
      }
    }
  }
}

Navn på mutasjoner

I GraphQL står vi fritt til å navngi operasjonene våre etter hva de faktisk gjør. Vi foretrekker derfor å bruke verb som samsvarer med domenespråket og vi prøver å unngå generiske mutasjoner. For eksempel:

• Vi foretrekker registrerSoknad heller enn lagreSoknad.
• Vi foretrekker godkjennSoknad og avvisSoknad fremfor behandleSoknad.

Alt eller ingenting

Vi lager som hovedregel mutasjoner som støtter bulk-oppdateringer. Det vil si at samme mutasjon kan endre på flere rader i databasen samtidig. Våre mutasjoner er implementert slik at endringen gjøres i én transaksjon. Det vil si at enten lykkes endringen for alle radene, eller så feiler den for alle.

Du velger selv hvilke data du vil ha tilbake

Det fleste mutasjonene våre returnerer et objekt som peker inn i Query-grafen. Dermed kan du hente oppdatert informasjonen fra grafen slik den ser ut etter at mutasjonen har skjedd. I eksempelet under har vi bedt om å få med mobilnummer i tillegg til den endrede adressen:

mutation MyMutation {
  endreFolkeregistrerteAdresser(
    input: [{id: "NzY6MTIzNCw4ODE", co: "c/o en god venn av meg", gate: "Gågata 3", postnummerOgSted: "0123 Oslo", land: "Norge"}, {id: "NzY6MTIzNCw4ODI", co: "c/o en god venn av deg", gate: "Gågata 4b", postnummerOgSted: "0123 Oslo", land: "Norge"}]
  ) {
    personProfiler {
      id
      folkeregistrertAdresse {
        co
        gate
        land
        postnummerOgSted
      }
      mobilTelefon {
        landnummer
        nummer
      }
    }
  }
}

Generell og spesifikk feilhåndtering

En hver GraphQL-forespørsel kan returnere to felter på toppnivå: "data" og "errors". Dersom hele eller deler av en forespørsel feiler, returneres den en liste med feilmeldinger i "errors"-feltet. Slike toppnivå-feilmeldinger betyr som regel at noe har gått galt på serversiden:

{
  "errors": [
    {
      "message": "Internal Server Error(s) while executing query",
      "locations": []
    }
  ],
  "data": null
}

Feil som oppstår på grunn av brudd på forretningsregler, foretrekker vi å implementere som egne typer i APIet. Mutasjonene våre vil derfor i payloaden som returneres for en forespørsel, gi en liste med oppdaterte objekter, eller en liste med feilmeldinger.

Noen mutasjoner er fortsatt uten feilhåndtering

I den eksperimentelle delen av FS GraphQL API, vil det fortsatt finnes en del mutasjoner som mangler feilhåndtering. Mønsteret som er beskrevet her, vil imidlertid bli implementert før disse løftes opp til stabil produksjon.

Feilmeldingene returneres av feltet errors. Dette peker på en union-type, og klienten må håndtere at det kan legges til nye feiltyper. Alle feilmeldingene implementerer et felles interface Error. En feilmelding vil alltid inneholde feltene message, som spesifiserer nærmere hva som gikk galt, og path, som identifiserer hvor i forespørselen feilen oppsto. Det kan hende vi i framtiden vil definere nye felter i tillegg til disse.

I eksempelet under prøver vi å registrere en permisjon for en student. Mutasjonen har to mulige feiltyper. UgyldigInput Er en felles feilmelding, som returneres dersom klienten har sendt inn data som bryter med maksimum feltlengde eller andre begrensninger på dataene i databasen. Denne mutasjonen har i tillegg en feilmelding UgyldigPermisjonsperiode, som returneres dersom det blir oppgitt en ugyldig permisjonsperiode.

Siden errors peker på en Union-type, må du bruke inline-fragments for angi hvilke feilmeldinger du vil ha tilbake. I følgende eksempel har vi bedt om begge to:

mutation RegistrerPermisjon {
    registrerPermisjonForStudenter(
        input: {
            studentVedInstitusjonId: "OTk6MTIzNCw4OTE",
            studieprogramId: "MTA2OjEyMzQsQU1ILU1VUzE",
            fraDato: "2024-01-01",
            tilDato: "2024-06-30",
            permisjonsprosent: 100,
            forventetNyttKullId: "NTg6MTIzNCxBTUgtTVVTMSwyMDI0LEjDmFNU",
            fravarsarsakId: "MTYzOjEyMzQsU1RVRFVUTA",
            journalnummer: "23/0202114",
            merknadUnd: "Registrert via FS GraphQL API"
        }
    ) {
        errors {
            ... on UgyldigInput {
                __typename
                message
                path
            }
            ... on UgyldigPermisjonsperiode {
                __typename
                message
                path
            }
        }
        permisjoner {
            id
        }
    }
}

Her vil du imidlertid ikke få eventuelle nye feilmeldinger som blir lagt til.

Siden alle feilmeldingene implementerer et felles grensesnitt, kan vi legge til et inline-fragment, som sørger for at vi får med oss også nye feilmeldinger som måtte bli lagt til i union-typen:

mutation RegistrerPermisjon {
    registrerPermisjonForStudenter(
        input: {
            studentVedInstitusjonId: "OTk6MTIzNCw4OTE",
            studieprogramId: "MTA2OjEyMzQsQU1ILU1VUzE",
            fraDato: "2024-01-01",
            tilDato: "2024-06-30",
            permisjonsprosent: 100,
            forventetNyttKullId: "NTg6MTIzNCxBTUgtTVVTMSwyMDI0LEjDmFNU",
            fravarsarsakId: "MTYzOjEyMzQsU1RVRFVUTA",
            journalnummer: "23/0202114",
            merknadUnd: "Registrert via FS GraphQL API"}
    ) {
        errors {
            ... on UgyldigInput {
                __typename
                message
                path
            }
            ... on UgyldigPermisjonsperiode {
                __typename
                message
                path
            }
            ... on Error {
                __typename
                message
                path
            }
        }
        permisjoner {
            id
        }
    }
}

Da vil du få med deg også nye feiltyper med message og path, men ikke eventuelle felter som er spesifikke for den nye feilmeldingen.

Hvis klienten din ikke er så opptatt av hvilke spesifikke feil som blir returnert, kan du nøye deg med å spørre etter Error-interfacet:

mutation RegistrerPermisjon {
    registrerPermisjonForStudenter(
        input: {
            studentVedInstitusjonId: "OTk6MTIzNCw4OTE",
            studieprogramId: "MTA2OjEyMzQsQU1ILU1VUzE",
            fraDato: "2024-01-01",
            tilDato: "2024-06-30",
            permisjonsprosent: 100,
            forventetNyttKullId: "NTg6MTIzNCxBTUgtTVVTMSwyMDI0LEjDmFNU",
            fravarsarsakId: "MTYzOjEyMzQsU1RVRFVUTA",
            journalnummer: "23/0202114",
            merknadUnd: "Registrert via FS GraphQL API"}
    ) {
        errors {
            ... on Error {
                __typename
                message
                path
            }
        }
        permisjoner {
            id
        }
    }
}

Da vil du også få nye feilmeldinger som blir lagt til med message og path, men ingen felter som er spesifikke for den enkelte feilmelding.

Introspeksjonsspørring

Følgende introspeksjonsspørring vil gi deg alle tilgjengelige mutasjoner:

{
  __schema {
    mutationType {
      name
      description
      fields {
        name
        description
        args {
          name
          description
          type {
            kind
            name
            ofType {
              kind
              name
            }
          }
        }
        type {
          kind
          name
        }
      }
    }
  }
}