API for NVDB Elveg

Autentisering

APIet krever at en bruker autentiserer seg med gyldig JSON Web Token (JWT) utstedt fra Statens Vegvesen. JWT skal plasseres i headerene til API forespørsler slik som dette Authorization: Bearer <Ditt JWT>.

Autentisering gjøres mot følgende realms:

• /External - Brukes i grensesnitt til innlogging for ansatte i Vegvesenet og eksterne brukere.
• /WSClients_Int - Brukes for å autentisere Maskin-til-maskin-kommunikasjon (M2M) med tjenestebrukere.

Elveg krever at brukeren har minst én av flere godkjente roller, dette gjelder både API og grensesnitt. Godkjente roller er:

• nva=3_veged_admin
• nva=7_utvalg_admin
• nva=9_system_admin

Autentiseringstjenesten til NVDB kan brukes for å hente ut et gyldig JWT. Bruk enten din egen bruker eller en tjenestebruker til å logge inn via /autentiser endepunktet. Husk å velge riktig brukertype. For personlige brukere skal typen EKSTERN benyttes. Tjenestebruker skal bruke TJENESTEBRUKER. Tokenet som skal brukes ligger under id_token i responsen fra autentiseringstjenesten. Vær oppmerksom på at JWT tilhører miljøet den hentes fra. Altså vil ikke et JWT fra produksjonsmiljø fungere i testmiljøene.

Et JWT har en gyldighet på 8 timer for brukere. Tjenestebrukere har begrenset gyldigheten til 1 time;

Opprette bestilling

Bestillingstjenesten er tilgjengelig som et REST API og kan brukes uten å gå gjennom grensesnittet. For at tjenesten skal godta kall må det legges ved et gyldig JWT utstedt fra SVV FAM. Den legges ved i Authorization header med verdi "Bearer X" hvor X er tokenet.

For å opprette en bestilling må det gjennomføres et POST kall til endepunktet:
https://elveg-order-service.atlas.vegvesen.no/api/v1/orders 
Bestillingsspesifikasjon legges ved som JSON i body.

Under ligger et eksempel på en slik body. Kommuner og objekttyper identifiseres av et ID som er definert i NVDB. Alle Enum verdier (roadCategories, projection, dataformat) kan finnes i API dokumentasjonen under "Schemas".

{
    "name":"Min bestilling",
    "municipalities":[ 1151, 1144 ],
    "roadCategories":[ "EURO_ROAD", "NATIONAL_ROAD", ],
    "linearRoadReferences":[ 923, 105, ],
    "projection":"ZONE_33",
    "dataFormat":"SOSI",
    "when":"2023-03-28T12:19:58.645Z"
}

Bestillingstjenesten svarer med den genererte IDen for bestillingen. I svaret ligger også kallet for å hente bestillingen vedlagt i Location headeren.

Laste ned bestilling

Bestillingstjenesten benytter to endepunkt for nedlasting av innholdet til bestillingen. Nedlasting gjennomføres slik for at nettleseren kan ha kontroll over nedlastingen og vi slipper å gjøre ekstra håndtering.

Kallene er som følger:

• https://elveg-order-service.atlas.vegvesen.no/api/v1/orders/{BESTILLING_ID}/sign-download?filename={FILNAVN}
• https://elveg-order-service.atlas.vegvesen.no/api/v1/orders/download?id={BESTILLING_ID}&filename={FILNAVN}&expire={EXPIRY}&hmac={HMAC}

/sign-download endepunktet er sikret bak JWT og tar inn ID til bestillingen og et filnavn. Bestillingstjenesten genererer en HMAC og expiry som kan brukes som nøkler for det andre endepunktet. Den genererte nøkkelen er bare gyldig i to minutter./download endepunktet er ikke sikret bak JWT men bruker verdiene i parameterene for å avgjøre om kallet har tillatelse til å laste ned. Alle de nødvendige parameterene mottas fra det første endepunktet og må fylles inn for dette kallet.