Rutiner

Vi forutsetter og bygger på en viss fremgang i arbeid med orden i eget hus hos deltagende virksomheter der noen datasett er dokumentert i en datakatalog. Dette kan enten være Digitaliseringsdirektoratets Felles datakatalog, eller en fremtidig katalog for høyere utdanning og forskningssektoren som høstes inn i Felles datakatalogen.

Vi skisserer en tilnærming til indre og ytre API basert på Gartners MASA arkitektur[1] som var brukt i evalueringen av Felles Studentsystem i 2020

1. Indre API

Indre API eksponerer masterdata (informasjon om objekter i domenet) som er strukturert i henhold til semantikk i domenet den tilhører, og må ta ansvar for den semantiske validiteten til data den eksponerer. Indre API er laget for å være mest mulig generell og ikke laget for noen spesifikk prosesskontekst.

[Vi tenker å utdype her på et senere tidspunkt.]

2. Ytre API

Ytre API benyttes i en forretningsprosesskontekst og datasett eksponert gjennom en ytre API er laget for å møte behovene til prosessen. Ytre API kan benyttes i både grunnleggende og bruksnære domener. En tilnærming til definisjon av APIer og datasett for prosesstøtte er beskrevet under.

  1. Melde behov, gjerne av datakonsumentene

    1. Tjenesteansvarlig kjører periodisk prosess for å samle innspill og prioritere

    2. Vurder å kjøre tjenestedesign workshop for å beskrive bruksscenariene

  2. Analysere behov og finne ut hvilke domener, kilder og datasett som er involvert

    1. Tjenesteansvarlig identifiserer berørte interessenter, potensielt andre tjenesteansvarlige, dataforvalter, domeneansvarlig og begrepsansvarlig

    2. Tjenesteansvarlig må vurdere og eventuelt sette i gang juridiske avklaringer omkring deling av data

  3. Kjør begrepsharmonisering etter behov med relevante interessenter

    1. Følg standarden om Begrepsharmonisering og begrepsdifferensiering og føringer fra Rammeverk for begrepskoordinering i KUDAF (kurs om begrepsarbeid er en utfyllende ressurs)

  4. Publiser nye eller oppdaterte begreper i UHF begrepskatalog (eventuelt i begrepskatalogen under Felles datakatalog)

  5. Identifiser hva må skapes, harmoniseres eller videreutvikles. Pass på at funksjonaliteten spesifisert i grensesnittet dekker kun det som trengs for å støtte brukstilfellet under utvikling som prinsipp for god design. I tillegg må all behandling av personopplysninger være adekvat, relevant og begrenset til det som er nødvendig for formålene de behandles for. Dette innebærer blant annet at det må vurderes om det definerte formålet kan oppnås med færre personopplysninger, eventuelt avidentifiserte opplysninger, samt at tilgangsvisning og lagringstid må søkes minimert til det som er nødvendig.

  6. Sikre at data i alle steg i verdikjeden passer til den tenkte anvendelsen.

  7. Definere API/datasett i team med representasjon fra både bruksmiljø og produsent. Det kan ta noen iterasjoner med utprøving av API før man er fornøyd. Senere oppdateringer kan kjøres som iterasjoner da man allerede har resultatene fra tidligere steg.

    1. Designe nødvendig API for brukskonteksten.

    2. Mappe nødvendig funksjonalitet til API fra grunnleggende domener.

    3. Designe «API mediation», det vil si hvordan datasettet spesifisert i det ytre APIet tilgjengeliggjøres. Oppgaven inkluderer mapping til indre API som benyttes med nødvendig oversetting av protokoller, formater og datastrukturer, samt etterlevelse av policy for sikkerhet og volumbegrensninger.

    4. Implementere tjenestene

    5. Koordinere mellom APIene for å sikre sammenhengende brukeropplevelse mellom APIene

    6. Publisere APIene og datasett i UHF API katalog (eventuelt felles datakatalog) i henhold til DCAT-AP-NO

3. Notifikasjoner

Når en hendelse endrer data hos en datatilbyder, og disse data deles gjennom datadeling med notifikasjon, skal det sendes en notifikasjon til datakonsument.
Notifikasjoner omhandler hvilke data i det tilhørende API som er endret. Notifikasjonen er sådan operasjonell, den melder fra om hvilke data som er endret, men ikke hvilken forretningshendelse som har inntruffet.

For å utvikle notifikasjoner følges tilsvarende prosess som for API over. Det vil si at notifikasjoner, som beskrevet i denne referansearkitekturen, er knyttet til API der datakonsumenten henter ut data. Det vesentlige av beskrivelse for datautvekslingen ligger derfor til utviklingen av API som hører sammen med notifikasjonen.

Spesielt for notifikasjoner gjelder følgende:

  1. Notifikasjonen skal gi en meningsfull indikasjon på hvilke data som er endret i form av liste over endrede attributter i datagrunnlaget.

  2. Notifikasjonen skal inneholde en referanse til ressursen (i API-et) der data kan hentes fra

  3. Etterstreb å modellere notifikasjoner etter etablerte standarder

  4. Sørg for at meningen notifikasjonene bærer er godt dokumentert i notifikasjonskatalogen

  5. Ressursen, det vil si det API som er knyttet til notifikasjonen, må være utformet slik at uthenting av data alltid gir siste gyldige versjon. På den måten vil innhenting hos datakonsument kunne være idempotent

Med «idempotent» er det i denne sammenheng ment at man kan kalle på den samme ressursen flere ganger og alltid få samme resultat.

Per i dag er CloudEvents den eneste generaliserte standarden for hvordan notifikasjoner bør utformes. Referansearkitekturen anbefaler at CloudEvents tas i bruk som standardformat for notifikasjoner. CloudEvents er utviklet i regi av Cloud Native Computing Foundation.

En notifikasjon utformet etter minstekravene til CloudEvents med JSON Event Format ser typisk ut:

{"id": "935ec740-d4a4-418d-b6c3-282d6fd2305b",

"specversion": "1.0",

"time": "2020-11-19T17:30:41.244Z",

"source": "urn:no-edu-orgreg:ntnu:ou:1260",

"type": "orgreg.v1.ntnu.dev.ou.create"}

I eksempelet på en notifikasjon ovenfor meddeles det at det har blitt opprettet en organisatorisk enhet ved NTNU med identifikatoren 1260.

Bruk av et felles notifikasjonsformat tilrettelegger for gjenbruk av komponenter på tvers av tjenester da en notifikasjon er velstrukturert og de informasjonsbærende elementer er strengt definert. I de tilfeller det er nødvendig å inkludere informasjonsbærende elementer som ikke er inkludert i standarden, er standarden mulig å utvide. Standarden legger også til rette for en rekke operasjonelle kapabiliteter (eksempelvis deduplisering) gjennom informasjonselementene som er påkrevet i standarden.

1. MASA: How to Create an Agile Application Architecture With Apps, APIs and Services Published 3 February 2020 - ID G00451136; Gartner