Info

Denne siden henvender sig til udviklere og data specialister hos regionens rådgivere, som ønsker at integrere til GeoGIS openAPI og DMP Stanlab reporting API fra egne systemer.

Indholdsfortegnelse

1 Indholdsfortegnelse
2 Introduktion
3 Fremgangsmåde
- 3.1 Stanlab Reporting API
- 3.2 GeoGIS openAPI
- 3.3 Autentifikation til Stanlab og GeoGIS openAPI
  - 3.3.1 Adgang via client credentials (kun DMP stanlab):
- 3.4 Adgang via Codeflow (dvs brugeren logge på via browser):
- 3.5 Postman collections
  - 3.5.1 GeoGISopenAPI - Codeflow
  - 3.5.2 Stanlab - clientid
- 3.6 Stanlab - codeflow

Introduktion

Det er muligt via API kald til GeoGIS openAPI og DMP Stanlab at integrere med egne løsninger. ARA-systemet (se ARA - AnalyseRekvisitions-App) anvender alene disse API'er til al dataudvekslingen mellem regionens GeoGIS og Stanlab. GeoGIS openAPI indeholder yderligere funktioner end det som pt. anvendes i ARA.

Fremgangsmåde

I det følgende beskrives API'er og hvordan man kan få adgang.

Stanlab Reporting API

DMP Stanlab reporting API, gør det muligt at sende rekvisitioner til laboratoriet (via Stanlab), og det er muligt, f.eks. at se status på prøver og rekvisitioner, samt hvilke analysepakker som laboratorierne udstiller.

Stanlab systemet forudsætter at analyseprøven og tilhørende feltmålinger allerede er oprettet i fagsystemet (GeoGIS) inden man kan lave rekvisitionen på prøven.

For beskrivelse af API henvises til:

Det er muligt at forespørge DMP stanlab APIvia RESTkald og graphQL, med graphQL kan man f.eks. lave forspørgsler på eksisterende rekvisitioner.

Som eksempel vil følgende kald returnere et json object med alle analyserekvisitioner efter 2023-01-01 (for den region man er logget ind med)

Post https://stanlab-api.miljoeportal.dk/v2/graphql

body:

query Requisitions {
    requisitions(from: "2023-01-01", laboratory: null) {
        requisitionId
        laboratoryTestReference
        ordered
        confirmed
        reported
        remarks
        sampleRegistered
        deleted {
            time
            user {
                name
                id
            }
        }
        laboratoryTest {
            finished
            remarks
            reported
        }
        packages {
            reference
            name
            turnaroundTime
            containers
            fingerprint
            matrix {
                description
                value
            }
        }
        containerReferences
        user {
            company
            id
            name
        }
        samplingContact {
            email
            name
            phone
        }
        contact {
            email
            name
            phone
        }
        remarks
        sample {
            sampleId
            label
            location
            remarks
            observationFacility {
                name
                observationFacilityId
            }
        }
        laboratoryContract {
            laboratory {
                name
            }
        }
    }
}

GeoGIS openAPI

GeoGIS openAPI er lavet for at understøtte stanlab api'et, således at man fra ARA eller andet system kan finde, oprette og slette data om f.eks. prøver forud for oprettelse af rekvisition hos DMP. På sigt kan api'et også udbygges med andre kald til understøttelse af andre datasæt, f.eks. jordprøver og pejlinger.

GeoGIS openAPI specifikationen, samt beskrivelse kan findes på https://feltdata.stoplight.io

Autentifikation til Stanlab og GeoGIS openAPI

Authentifikation foregår via Danmarks Miljøportals brugerstyring. Dette gælder for begge API'er. Det kræver authentifikation at anvende de to api'er, og det kan lidt vanskeligt at sætte dette op så man får adgang. I det følgende er adgangen beskrevet. I øvrigt henvises til DMP's infoside Brugerstyring: Adgang til fagsystemer gennem Danmarks Miljøportal – Danmarks Miljøportal (miljoeportal.dk)

Det er muligt at forespørge DMP stanlab API via RESTkald og graphQL. Man kan tilgå med Oauth 2.0 codeflow authentification (dvs med DMP bruger og adgangskode via browser login), dette vil give skriveadgang. Man kan også tilgå via clientid + client-secret (dvs uden login via browser). Dette er kun muligt med læseadgang.
For GeoGIS openAPI kan man kun anvende codeflow authentification, dvs det er ikke pt. muligt at lave systemintegration uden at der er en bruger som logger ind via browser.

I det følgende beskrives det grundlæggende setup for login. For selve clientID og og secret henvises til regionernes kontaktpersoner.

Beskrivelsen tager udgangspunkt i et setup i Postman. Postman er et godt værktøj til test og design af api'er, og findes i en gratis udgave. Et andet alternativ er Insomnia. Det er muligt at importere API specifikationen direkte til f.eks. Postman så man får alle kald vist. Dette gøres via import af yaml filen fra stanlab specifikationssiden samt fra GeoGIS openapi specifikationssiden.

Adgang via client credentials (kun DMP stanlab):

Anvend nedenstående til at få et token, der kan anvendes i efterfølgende kald.

Access token url	https://log-in.miljoeportal.dk/runtime/oauth2/token.idp
auth data in	Request Headers
Header prefix:	Bearer
Grant type	client Credentials
client id	spørg regionen
client secret	spørg regionen
scope	openid offline_access stanlab_read stanlab_write
client authentication	'send clien credentials in body'
audience	https://stanlab-api.miljoeportal.dk

Nedenstående et eksempel på login udført med Postman:

Herefter kan man f.eks. få data for en prøve via GUID id'en på prøven i GeoGIS:

DMP udstiller data fra GeoGIS prøven via et kald fra DMP til det reporting API der findes hos regionen.

Adgang via Codeflow (dvs brugeren logge på via browser):

Access token url	https://log-in.miljoeportal.dk/runtime/oauth2/token.idp
auth data in	Request Headers
Header prefix:	Bearer
Grant type	Authorization Code
Callback URL	https://test.ara-regioner.dk/oidc-callback ovenstådende virker med clientid geogis-ara-geogis som er det clientid som ARA anvender. Andre callback url kan også anvendes, men skal være specificeret hos DMP for det gældende clientid. f.eks. kan man få et clientid der anvendes i Postman, så den selv kan hente token via browseren. dvs callback url'en https://oauth.pstmn.io/v1/callback det burde også være muligt at anvende
client id	region-ara-geogis eller anden clientid (regionen kan hjælpe med dette)
client secret	ingen
scope	openid offline_access stanlab_read stanlab_write
client authentication	'send clien credentials in body'
audience	https://stanlab-api.miljoeportal.dk
Resource	http://localhost/signin-oidc
Audience	https://stanlab-api.miljoeportal.dk

Følgende eksempleskærmbilleder fra postman ved login:

Herefter viderestiller browser til ny side, hvoraf token kan findes i url'en:

Postman collections

Følgende postman-collections kan bruges til test af login via Postman. indholdet af disse collections er kun eksempler og indeholder langt fra alle kald. Der henvises i stedet til API specifikationssiderne.

GeoGISopenAPI - Codeflow

NB, URL'er er opsat til testmiljøet, og man skal derfor have et login til DMP testmiljøet og ens bruger skal være opsat i regionens geogis-testdatabase. Man kan nemt ændre til at køre på driftmiljøet ved at ændre i variablerne på 'collection'

Stanlab - clientid

Kald til DMP stanlab testmiljø via clientid+secret. Kan nemt tilpasses til køre mod driftmiljø.

Stanlab - codeflow

Kald til DMP stanlab testmijø ved brug af codeflow (browser brugerlogin)

API kald til GeoGIS openapi og DMP stanlab