GraphQL

Vi benytter GraphQL for oppslag av arbeidsforhold fra Aa-registeret. Dette gir konsumenter muligheten til å spesifisere hvilke felter de ønsker i retur når de utfører en spørring.

1. Skjemadefinisjon
   1. Tegn og Typer
2. Introspection
3. Verktøy for testing
4. Eksempelspørringer

Skjemadefinisjon

Tegn og Typer

Skjemaet definerer et sett med typer som GraphQL benytter når man utfører en spørring

Kort forkaring av tegn:

[type] = Liste av type
f.eks:
droid: [Droid]

type = Enkelt objekt
f.eks:
jedi: Jedi

! = non-nullable
f.eks:
spaceships: [Spaceship!]!

NB: Vår løsning benytter ikke non-nullable.Med andre ord kan ALLE typer og lister være null!

Eksempler på non-nullable:

droid: Droid!
- Forklaring:
  'Droid' kan aldri være null / har alltid en verdi
- Eksempler:
  "droid": { ...Data... }    // gyldig
  "droid": null              // ugyldig

spaceships: [Spaceship]!
- Forklaring:
  'Spaceship' kan være null, men ikke listen
- Eksempler:
  "spaceships": { [] }             // gyldig
  "spaceships": { [null] }         // gyldig
  "spaceships": { [...Data...] }   // gyldig
  "spaceships": null               // ugyldig

spaceships: [Spaceship!]!
- Forklaring:
  Både 'Spaceship' og listen kan aldri være null / har alltid en verdi
- Eksempler:
  "spaceships": { [...Data...] }          // gyldig
  "spaceships": { [...Data...], null }    // ugyldig
  "spaceships": { [null] }                // ugyldig
  "spaceships": null                      // ugyldig

spaceships: [Spaceship]
- Forklaring:
  Alt kan være null

Typer kan være primitiv (f.eks: String) eller et objekt som inneholder andre typer:

type Character {
    name: String!
    appearsIn: [Episode]!
}

Som vist over er inneholder typen ‘Character’ 2 typer. Dersom vi ser nærmere på feltet ‘appearsIn’ ser vi at den er en liste av enum ‘Episode’

"""
Valid Star Wars movies
"""
enum Episode {
    NEWHOPE
    """
    No, I am your father.
    """
    EMPIRE
    JEDI
}

Som vi ser inneholder ‘Episode’ 3 verdier, og kan i tillegg ha en beskrivelse. Beskrivelser er teksten skrevet ved bruk av følgende format: “"”…”””. Dette er verdier man får returnert dersom man ber om ‘description’ ved «Introspection»

Introspection

Introspection er en måte å lese skjema på.Ved en spørring til GraphQL endepunket kan man enklet få forklart blandt annet tilgjengelige spørringer (queries) og forklaring av typer.

For full beskrivelse av Introspection kan man lese dokumentasjonen på GraphQLs hjemmeside.

Her er en enkel spørring for å få tak i alle tilgjengelige spørringer (queries).

__schema {
    queryType {
        name
    }
}

{

Dersom man ønsker å forklart et spesielt felt kan man sende noe som dette:

{
    __type(name: "Droid") {
        name
        description
    }
}

Verktøy for testing

Vi anbefaller nyere versjoner av Postman for testing eller for å bli kjent med GraphQL.

For vår tjeneste kreves det et gyldig token fra Maskinporten.

NB: Ikke opprett konto/logg inn i Postman da den cacher resultatsettet og da potensielt lekker data. Det er en litt skjult “skip registration” knapp på introduksjons-siden.

Eksempelspørringer

NB JSON støtter ikke en streng over flere linjer og eksemplene vil derfor fremstå som uoversiktlig. Hele “query” feltet må derfor ligge i en linje.

Eksempel på gyldig query:

{
  "query": "query DroidById($id: ID!) {droid(id: $id) {name}}",
  "variables": {
    "id": "123456789"
  }
}

Samme spørring som eksempelet over, men med gal formattering:

{
  "query": "query DroidById($id: ID!) {
    droid(id: $id) {
      name
    }
  }",
  "variables": {
    "id": "123456789"
  }
}