Oversikt

NVDB API Skriv eksponerer et sett med REST-baserte endepunkter for registrering og vedlikehold av data i Nasjonal vegdatabank (NVDB). Sammen med NVDB API Les utgjør disse endepunktene en komplett tjenesteportefølje for utviklere av fagsystemer som har behov for integrasjon med NVDB. APIene og NVDB eies og forvaltes av Statens vegvesen.

Registrering og vedlikehold av NVDB-data beskrives i et endringssett som behandles asynkront via endringssett-endepunktene. Et endringssett kan manipulere både vegobjekter og vegnett, men sistnevnte er forbeholdt spesifikke vegnettsklienter. I tillegg finnes støtte-endepunkter for:

• Beregning av stedfesting for vegobjekter med geometri
• Uthenting av låser, oppdrag og transaksjoner fra NVDB
• Konvertering fra andre dataformater til endringssett
• Innsyn i tildelte datarettigheter (autorisasjon)

Prinsipper

• Endepunktene som representerer ressurser/entiteter følger designprinsippene til Representational State Transfer (REST).
• APIet er HTTP-basert. For å hente informasjon om en ressurs benyttes en GET-request. For å registrere eller oppdatere informasjon om en ressurs benyttes POST. Sistnevnte brukes også mot rene kommando-endepunkter. Responser vil ha en HTTP-statuskode som indikerer requestens korrekthet når det gjelder verb, URL, payload-format, tilgangskontroll m.m.
• Alle endepunkter støtter payloads både i JSON og XML-format. En respons får samme format som requesten, med mindre noe annet er angitt med en Accept-header.
• Alle URLer, URL-parametere og payloads, både i requester og responser, bruker norske domenebegreper.

Forutsetninger

• Alle requester skal ha følgende headere:
  • X-Client skal angi navnet på klienten som anroper APIet.
  • X-Request-ID skal angi en unik identifikator (UUID) for requesten. Denne gjenbrukes i eventuelle requester som NVDB API Skriv gjør til andre baksystemer.
• Alle requester må inneholde et gyldig autentiseringstoken, i form av en Authorization-header.
• Brukeren må ha relevante roller i Statens vegvesens LDAP-register.
• Dersom brukeren skal registrere eller vedlikeholde data i NVDB, må hun være tildelt datarettigheter i NVDB API Skriv. Datarettigheter gir tilgang til spesifikke geografiske områder, vegtyper og vegobjekttyper.

Miljøer

NVDB API Skriv er tilgjengelig i tre ulike miljøer hos Statens vegvesen:

Miljø	Formål	Basis-URL
UTV	Utvikling	https://nvdbapiskriv.utv.atlas.vegvesen.no/
STM	Systemtesting	https://nvdbapiskriv-stm.utv.atlas.vegvesen.no/
ATM	Akseptansetesting	https://nvdbapiskriv.test.atlas.vegvesen.no/
PROD	Produksjonsdrift	https://nvdbapiskriv.atlas.vegvesen.no/

De fire miljøene benytter hver sine instanser av NVDB. Alle NVDB instanser blir jevnlig oppdatert med dump fra PROD.

STM og ATM er normalt ikke eksponert gjennom brannmur mot internett, slik at klientanrop mot disse bare kan gjøres fra Statens vegvesen sitt lokalnett. Derimot vil vi åpne opp brannmuren til statiske IP-er for at eksterne kan teste systemene sine mot NVDB API Skriv. Kontakt nvdb@vegvesen.no om dette er et behov.

For utvikling og innledende testing er det også mulig for klientutviklere å integrerer seg mot en lokal Docker-container med NVDB API Skriv. Docker-imaget, som fritt kan lastes ned fra Docker Hub, oppdateres fortløpende i tråd med videreutvikling av NVDB API Skriv. Imaget eksponerer i tillegg til NVDB API Skriv, simulerte endepunkter for autentisering og andre infrastrukturtjenester hos Statens vegvesen. Basis-URL ved anrop til Docker-containeren er http://localhost:8010/nvdb/apiskriv/.

Advarsel

Docker-imaget inneholder IKKE alle valideringene. Dette betyr at endringssett som blir godkjent på Docker imaget ikke nødvendigvis blir det i produksjon.

Support

Forbedringer og feilrettinger i NVDB API Skriv rulles ut kontinuerlig. Endringer som er relevante for klienter og klientutviklere er beskrevet i en endringslogg.

Tekniske spørsmål omkring bruk av endepunktene sendes til nvdb-api@vegvesen.no.

Administrative henvendelser, f.eks. forespørsler omkring brukere, roller og datarettigheter, kan sendes til nvdb@vegvesen.no.