API for NADAG innmelding

API-et for innmelding av NADAG-data følger REST-konvensjoner for HTTP-verb og sti basert på entitetsnavn:

  • POST brukes for å opprette nye entiteter, PUT for å erstatte eksisterende og DELETE for å fjerne

  • stien følger den hierarkiske strukturen til modellen: GeotekniskUnders/{guId}/undersPkt/{gbId}, hvor undersPkt er aggregeringsassosiasjonen mellom GeotekniskUnders og GeotekniskBorehull

  • data som vedlegges har mime-typen application/json

I dagens (utkast til) API er de to øverste nivåene i modellen, altså GeotekniskUnders og GeotekniskBorehull redigerbare som entiteter. En kan sende inn hele strukturen av grunnundersøkelsen med borehull i én POST-forespørsel evt. erstatte med PUT, men en kan også legge til, oppdatere og fjerne spesifikke borehull for en gitt undersøkelse.

Vi har fått tilbakemelding om at det kan være ønskelig med flere nivå, så en kan sende inn nye metode-data uten å måtte sende inn et helt borehull med alle eksisterende borehullundersøkelser og metode-data i tillegg. Tilsvarende gjelder også GeotekniskDokument, som vi tenker har størst prioritet som utvidelse.

Støtte for opplasting av filer (vedlegg) knyttet til GeotekniskDokument er i et eget vedlegg-API.

Responsen fra API-et bruker de vanlige HTTP-statuskodene for å si om en forespørsel m/data ser grei ut (rent teknisk). I tillegg returneres et eget respons-objekt på JSON-format som inneholder ekstra valideringsinformasjon. F.eks. så er det en del påkrevde felt i modellen, og heller enn å avvise hele innsendingen, så får en 200 OK og en liste over hvilke felt som mangler. Feil i geomtri rapporteres på samme måte. Det vil etterhvert bli publisert en (omfattende) oversikt over valideringsregler.

Valideringsanmerkningene vil blir lagret sammen med innsendingen og vil være synlige i administrasjonsapp-en. Det er foreløpig ikke tatt stilling til hvilke eller hvor mange feil som vil blokkere en evt. publisering av innmeldinger.

Datamodell for innmelding-API-et

NADAGs datamodell er basert på SOSI-standarden for Geotekniske undersøkelser, som en kan lese mer om i følgende dokumenter:

Enterprise Architect-modellen for produktspesifikasjonen er utgangspunktet for data-modellen i API-et. Den er transformert til Java-klasser vha. ShapeChange-rammeverket og en egenskrevet transformasjon:

  • feature-typer er transformert til POJO-klasser, med tom konstruktør, private felt og get- og set-metoder

  • datatyper er transformert til record-klasser

  • kodelister er transformert til enum-klasser

For klassenavn er norske tegn æ, ø og å gjort om til to ae, oe, aa, mens for felt og metoder er norske tegn beholdt.

Klassene er annotert med

For grunnleggende datatyper brukes Java sine egne, samt egne record-klasser for geometri (Point, LineString, Polygon, osv.), som vi har laget for å støtte geojson-formatet. Sistnevnt bruker jsonb-annotasjoner for serialisering og deserialisering.

Test-API for innmelding

For at leverandører og andre interessenter skal kunne teste ut API-et, har vi satt opp en tjener med test-API-et, slik det så langt er definert og implementert:

>> Mer om funksjonalitet i test-API-et

Test-API for vedlegg

For at leverandører og andre interessenter skal kunne teste ut vedlegg API-et, har vi satt opp en test-tjener med dette vedlegg-API-et, slik det så langt er definert og implementert:

>> Mer om funksjonalitet i vedlegg-API-et

Java-modul for datamodell

Datamodellen genereres og pakkes i en egen jar-fil (Java-arkiv), og om ønskelig kan vi gjøre den tilgjengelig som maven-artifakt så den kan refereres til som avhengighet med GAV-koordinater. Denne kan være nyttig dersom en skal bruke Java for realisering av en innmeldingsklient. Det kan være aktuelt å generere tilsvarende for andre språk, f.eks. typescript og C#, evt. vil vi legge til rette for at andre skal kunne gjøre det, enten fra openapi-dokumentasjonen eller basert på ShapeChange.

Autentisering med Maskinporten

API-et for innmelding av NADAG-data benytter Maskinporten som autentiseringsmekanisme (i tillegg til Id Porten). Hvis man ønsker å benytte seg av Maskinporten må dette avtales spesielt med NGU. Dette gjøres ved å følge følgende aksjonspunkter:

  • Ta kontakt med NGU (tilbyder) for å få deres organisasjon (konsument) godkjent og definert som gyldig konsument av API-et.

  • Opprett en ny integrasjon for deres organisasjon på samarbeidsportalen til Digitaliseringsdirektoratet (https://sjolvbetjening.samarbeid.digdir.no/auth/login). Dette må gjøres at en person som har signaturrett på vegne av organisasjonen som ønsker tilgang.

  • Det må genereres et nøkkelpar (privat og offentlig nøkkel) som skal brukes under autentisering og den offentlige nøkkelen til en organisasjon må lastes opp når man oppretter denne integrasjonen. Det er laget en fin guide for dette her som kan brukes i denne forbindelse: https://docs.altinn.studio/nb/notifications/guides/maskinporten-client/

  • Integrasjonen er nå klar til testing. NGU har utviklet en eksempel klient i Java for dette som kan være behjelpelig i denne fasen.