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 og PUT for å erstatte eksisterende
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 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 (GU) med borehull i én POST-forespørsel evt. erstatte GU-en med PUT, men en kan også legge til, oppdatere og fjerne spesifikke borehull for en gitt GU. Det er mulig å oppdatere en GU uten å måtte sende inn eksisterende borehull, geotekniske dokumenter, tolkede punkt eller feltundersøkelser, ved at en angir hvilke av disse som skal ignoreres.

Vi har fått tilbakemelding om at det kan være ønskelig å kunne oppdatere andre entiteter (eller lister av dem), f.eks. metodedata eller geotekniske dokumenter. Dette kompliseres av måten GU-er versjoneres på, og blir ikke prioritert i denne omgang, men kan komme senere.

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

Validering av innmeldte data

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. Dersom feilene er alvorlige nok, så brukes 422-statuskoden for å indikere at innsendingen ikke er lagret.

Valideringsanmerkningene blir lagret sammen med innsendingen (såfremt innsendingen er gyldig) 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.

Dersom en kun ønsker å validere en GU uten å lagre den, f.eks. for å sjekke om dataene har god nok kvalitet eller er korrekt formatert, så kan en bruke et eget validering-endepunkt.

>> Detaljer om valideringsreglene

Datamodell for innmelding-API-et

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

Internt har vi generert Java-klasser basert på denne datamodellen, disse er annotert med OpenApi-annotasjoner fra Microprofile OpenApi, og fra dette genereres det OpenApi-dokumentasjon som er tilgjengelig på et eget endepunkt. Dette gjør det bl.a. mulig å generere klientkode for andre språk enn Java, f.eks. Python og Typescript.

Geometri-felt som GeotekniskUnders sitt område eller GeotekniskBorehull sin posisjon kodes som JSON iht. GeoJSON-standarden, altså som et JSON-objekt med type-felt (Point, LineString, Polygon, osv.) og coordinates-felt (array med koordinater med dimensjon tilsvarende typen).

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:

Test-tjener: https://test.ngu.no/api/nadag/innmelding/v1
OpenAPI-dokumentasjon: https://test.ngu.no/api/nadag/innmelding/openapi/v1
Swagger-UI: https://test.ngu.no/api/openapi-ui/ Skriv deretter inn /api/nadag/innmelding/openapi/v1 i feltet "Explore" for å se dokumentasjonen i et brukervennlig grensesnitt.
Administrasjonsapplikasjon for innmeldte data: https://test.ngu.no/app/nadag/innmelding/

>> Mer om funksjonalitet i test-API-et

API-et for opplasting av vedlegg er tilgjengelig på samme maskin:

Test-tjener: https://test.ngu.no/api/vedlegg
OpenAPI-dokumentasjon: https://test.ngu.no/api/nadag/innmelding/openapi/vedlegg (også tilgjengelig i Swagger-UI-et over)

>> Mer om funksjonalitet i vedlegg-API-et

Autentisering med Maskinporten

API-et for innmelding av NADAG-data benytter Maskinporten som autentiseringsmekanisme (i tillegg til Idporten). Hvis man ønsker å benytte seg av Maskinporten må dette avtales spesielt med NGU:

Ta kontakt med NGU (tilbyder) for å få din organisasjon 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 av 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 nyttig å se på i denne fasen: https://github.com/ngu/nadag-innmelding-client-example
Ved innveksling av token må en oppgi brukeren som data skal sendes inn på vegne av, i form av en såkalt UUID. Denne personen må allerede være registert som bruker av administrasjonsapplikasjonen, og UUID-en finner hen på profil-siden.