Gå til hovedinnhold

Designvalg

I dette dokumentet dokumenterer vi designvalg som er gjort i forbindelse med utvikling av APIer i FS-plattformen. Hensikten er å sørge for mest mulig konsistente APIer. Dette dokumentet skal være førende for fremtidig API-utvikling på FS-plattformen. Designvalgene er gjort dels i en REST- kontekst, og dels i en GraphQL-kontekst. Designvalgene regnes som gjeldende for begge teknologier med mindre noe annet er spesifisert.

Designvalg som gjelder for både REST og GraphQL​

Se oppslagsboka: Navngiving av felter og objekter i FS-plattformen

Kolonner med navn som begynner med "STATUS_" i FS​

I FS brukes prefikset "STATUS_" for å varsle at kolonnen kun tar verdiene "J" og "N". I APIene oppnår vi det samme ved å definere feltet som et Boolean-felt. "STATUS_"-delen av navnet er dermed unødvendig, og skal aldri brukes i feltnavn i APIet. "STATUS_AKTIV" som finnes i mange tabeller gjengis for eksempel alltid som "aktiv" i APIene.

Kodeverditype (felleskode / lokal kode)​

Mange kodetabeller inneholder kolonnen "KODEVERDITYPE", som tar verdiene "F" (felleskode) og "L" (lokal kode). I FS-plattformen blir "F" transformert til verdien true, og "L" blir transformert til false. Dette feltet skal alltid hete "felleskode".

Felter som er nøkler i FS-kjernen​

  • Sammensatte nøkler:
    • De delene av nøkkelen som refererer til andre objekter, eksponeres som IDer som peker på det andre objektet
    • Deler av nøkkelen som er data om objektet selv, eksponerer vi som ordinære datafelter
  • Felter av typen “Kode” og “nummer”:
    • Løpenumre som settes automatisk ved oppretting av nye rader er implementasjonsdetaljer, som vi ikke eksponerer (med mulig unntak for personløpenummer)
    • Felter som fungerer som “rene” IDer eksponerer vi i utgangspunktet ikke. Dette betyr at ved implementering av POSTs og mutations, må APIet ta kostnaden ved å generere og sette verdier i disse feltene.
    • Enkelte felter som teknisk sett er IDer, brukes på en måte i sektoren som gjør at de i praksis fungerer som datafelter (eksempelvis “emnekode”). Dersom slik bruk ikke kan unngås, bør APIet også eksponere dem som data. Dette bør skje i samråd med sektoren.

Flerspråklige felter​

Se oppslagsboka: Flerspråklighet

Modellering​

  • Vi innfører en del struktur/informasjon som ikke finnes i FS-modellen (men som typisk vises i FS-klienten)
    • Fra-/til => periode
      • DATO_FRA/TIL => datoperiode
      • ARSTALL/TERMINKODE_FRA/TIL => terminperiode
      • ARSTALL/MANEDNR_FRA/TIL => manedsperiode

Referanser til kodetabeller​

Se oppslagsboka Kodetabeller i FS

Designvalg for GraphQL​

Følgende designvalg er kun gjeldende for GraphQL-APIer.

En kant i GraphQL er en referanse fra én node til en annen (dvs. alltid med en spesifikk retning). Kanter navngis etter hvilken node den peker på. Hvilken node kanten går fra, vil gå frem av konteksten når man gjør en spørring. Campus for en programStudierett navngis f.eks. ganske enkelt "campus".

For "én-til-mange-relasjoner" bruker vi flertallsform. Kanten fra StudentVedInstitusjon til ProgramStudierett heter f.eks. "programStudieretter".

En node kan ha mer enn én kant til en annen. Eksempelvis har PersonProfil en node mot Adresse. Denne heter "folkeregistrertAdresse" og ikke "adresse", fordi vi ønsker å kunne legge til andre adressetyper senere.

Oppslag​

Oppslag på nøkkel er et vanlig bruksmønster, spesielt for integrasjoner. Brukeren har én eller flere nøkler (av samme type) og ønsker å hente informasjon fra APIet vårt.

Når vi lager felt for oppslag gjelder følgende designregler:

  1. Vi skal alltid støtte batchoppslag
  2. Ett oppslagsfelt per nøkkeltype
  3. Hver entitet i resultatlisten samsvarer med nøkkelen på samme sted i inputlisten

Disse reglene gir følgende skjemadesign:

    studieprogramGittStudieprogramkoder(
        eierInstitusjonsnummer: String!
        studieprogramkoder: [String!]! @field(name: "STUDIEPROGRAMKODE")
    ): [Studieprogram]

Her ser vi at navnet på feltet begynner med navnet på typen man slår opp (i flertall). Deretter har vi bindeordet Gitt, etterfulgt av navnet på nøkkeltypen man oppgir. Som følge av designregel 3 ovenfor, så kan resultatlisten inneholde null-verdier for nøkler som ikke finnes eller som hen ikke har tilgang til.

Feilmeldinger for queries​

Opplegget som er definert for mutations over er gjenbrukbart også for queries, men det er foreløpig ikke tatt stilling til om det er ønskelig med tilsvarende feilhåndtering på querysiden.