API-dokumentasjon

Oppdatert API-dokumentasjon for versjon 3

Bruk heller dokumentasjon for versjon 3 av NVDB api https://nvdbapiles-v3.atlas.vegvesen.no/dokumentasjon

De sidene du besøker akkurat kan fungere godt for å få et overblikk over NVDB datamodell, men er utdatert på en del tekniske detaljer.

Gammel dokumentasjon

Retningslinjer for bruk av APIet.

Bruk av data

Informasjon fra Nasjonal vegdatabank tilgjengeliggjøres under Norsk lisens for offentlige data.

Informasjonen kan, med de begrensningene som følger av lisensen, brukes til ethvert formål og i en enhver sammenheng. Informasjonen kan inneholde feil og utelatelser, og Statens vegvesen gir ingen garantier for informasjonens innhold eller aktualitet.

Ved bruk av informasjon fra Nasjonal vegdatabank, skal det refereres til Statens vegvesen. Følgende tekst kan for eksempel benyttes:

«Inneholder data under norsk lisens for offentlige data (NLOD) tilgjengeliggjort av Statens vegvesen.»

Autentisering

Det er ikke nødvendig å registrere en bruker for å bruke APIet til å lese data fra NVDB. Det anbefales imidlertidig at kontaktperson og applikasjonsnavn angis gjennom HTTP-headere.

	"X-Client": "NVDB Rapporter"
  "X-Kontaktperson": "ola@nordmann.no"

Responsformater

Valg av respons angis ved hjelp av HTTP-headeren Accept. På alle endepunkt er JSON og XML tilgjengelige formater. JSON benyttes som standard.

Standardmediatypene application/json og application/xml vil til enhver tid være alias for nyeste responsrevisjon. For å unngå at klienter brekker er det anbefalt å bruke Accept-headeren, og angi responsrevisjon eksplisitt.

Accept: application/vnd.vegvesen.nvdb-v2+json
Accept: application/vnd.vegvesen.nvdb-v2+xml

For å gjøre det lettere å bla gjennom APIet ved hjelp av en nettleser, er det mulig å angi format direkte som en del av URI. Eksempel:

GET /vegobjekttyper.json
GET /vegobjekttyper.xml

Hent oppdaterte data

Vi oppfordrer våre brukere til å hente data i sanntid, fremfor å laste ned store datasett i bulk, med jevne mellomrom.

For dette tilbys endepunktet /vegobjekter/{id}/endringer

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

Pretty print

Dersom brukeren av ønsker formatterte svar fra APIet kan parameteren pretty=true brukes. Dette påvirker både XML- og JSON-formatene.

Feilsituasjoner

APIet har som mål å feile så raskt som mulig for å assistere brukeren. I den grad det er mulig vil alle kall til endepunkter returnere en liste med beskrivende feilobjekter. Dette vil supplere HTTP-statuskoden.

JSON-eksempel

[
    {
        "code": 4013,
        "message": "Ukjent parameter: vegvdeling",
        "help_url": "https://www.vegvesen.no/nvdb/api/dokumentasjon/api/page/3"
    }
]

Feilkoder

HTTP Status Feilkode Beskrivelse
404 4012 Objekt ble ikke funnet.
415 4001 Denne mediatypen er ikke støttet.
422 4000 Noe er galt med brukerens input.
422 4002 Feil i spesifisering av heltallsverdi.
422 4003 Feil i spesifisering av heltallslisteverdi.
422 4004 Manglende obligatorisk felt.
422 4005 Feil i spesifisering av tekstverdi.
422 4006 Feil i spesifisering av tekstlisteverdi.
422 4007 Feil i spesifisering av datoverdi.
422 4008 Feil i spesifisering av boolsk verdi.
422 4009 Konflikterende feltverdier spesifisert.
422 4010 Feil i spesifisering av flyttallsverdi.
422 4011 Feil i spesifisering av flyttallistesverdi.
422 4013 Ukjent felt spesifisert.
422 4014 Dette feltet kan kun forekomme én gang.
500 5000 Uventet feil har oppstått.
500 5001 Feil med kommunikasjon med databaser.
500 5002 Typeregisteret mangler.

I tillegg vil feilresponser ha header X-REQUEST-ID som du kan bruke om du kontakter oss om feilen, slik at det er lettere å hjelpe deg.

Evolusjonsstrategi

Kort fortalt vil det fungere på følgende måte:

Det er viktig å forstå forskjellen på brekkende og ikke-brekkende endringer for å forholde seg til hvordan NVDB-APIet endrer seg.

Brekkende endringer

En brekkende endring vil være et endepunkt som forsvinner eller en parameter som forsvinner eller får ny betydning. Dermed tvinges brukeren til å endre sin klient.

Ikke-brekkende endringer

Hvis en API-versjon får et nytt endepunkt eller en ny parameter anses dette som en utvidelse. I dette tilfeller tvinges ingen klienter til å endre seg.

Responsrevisjon

I tillegg til API-versjon er responsene versjonert. I mellom disse revisjonene kan brekkende endringer forekomme. Alle forespørsler til APIet bør indikere korrekt responsrevisjon.

Endringer i datakatalogen

NVDB API forholder seg til den oppdaterte Datakatalogen til enhver tid. Dersom et datafelt blir endret, f.eks. fra heltall til flyttall, vil samtlige responsrevisjoner endre seg.