Fra database til API - Kort fortalt

Når vi ønsker å hente, lage eller redigere noe i FS databasen kan vi uttrykke hva vi vil gjøre i et GraphQL-API. GraphQL er et spørrespråk for APIer hvor API-konsumenter ber be om akkurat de dataene de ønsker. Under ser du eksempel på en GraphQL spørring som henter personer sin emailadresse.

query MyQuery {
  personEmailer(eierInstitusjonsnummer: "1234") {
    emailadresse
  }
}

For å kunne uttrykke hva vi vil gjøre i GraphQL-API er vi først nødt til å beskrive FS data i et GraphQL skjema.

type PersonEmail @table(name: "PERSON") {
  emailadresse: String
}

GraphQL-skjemaet definerer hvilke data API-konsumentene skal kunne hente og redigere og hvordan data henger sammen.

type Query {
  personEmailer(
    eierInstitusjonsnummer: String! @field(name: "INSTITUSJONSNR_EIER")
  ): [PersonEmail]
}

Til slutt, må det lages kode som sørger for at alle operasjonene som er definert i GraphQL-skjemaet lar seg besvare av GraphQL-API. Dette kan Graphitron hjelpe til med.

public CompletableFuture<List<PersonEmail>> personEmailer(String eierInstitusjonsnummer,
        DataFetchingEnvironment env) throws Exception {
    return new DataFetcher(env, this.ctx).load(
            (ctx, selectionSet) -> queryDBQueries.personEmailerForQuery(ctx, eierInstitusjonsnummer, selectionSet)
    );
}

public List<PersonEmail> personEmailerForQuery(DSLContext ctx,
        String eierInstitusjonsnummer, SelectionSet select) {
    return ctx
            .select(
                    DSL.row(
                            select.optional("emailadresse", PERSON.EMAILADRESSE).as("emailadresse")
                    ).mapping(Functions.nullOnAllNull(PersonEmail::new)).as("personEmail")
            )
            .from(PERSON)
            .where(PERSON.INSTITUSJONSNR_EIER.eq(eierInstitusjonsnummer))
            .orderBy(PERSON.getIdFields())
            .fetch(it -> it.into(PersonEmail.class));
}

Graphitron er et verktøy som genererer kode basert på skjemaet vi har beskrevet. For at Graphitron skal kunne lage kode som gjør database operasjoner som henting eller endring av data må Graphitron ha Java-klasser som beskriver data entiteter i FS. Dette får Graphitron fra Kjerne-API. Kjerne-API bruker jOOQ for å generere Java-klasser fra databasetabeller.

Med den genererte koden basert på et skjema som beskriver FS data vil vi kunne uttrykke en spørring i GraphQL-API og få forventet respons tilbake.

Illustrasjonen under viser hvordan disse FS-plattform komponentene henger sammen.

Videre dokumentasjon går mer i dybden på det vi har skrapet overflaten på her.