Gå til hovedinnhold

Introduksjon

Velkommen til NVDB API Les V4 - den nyeste versjonen av NVDB API Les. Vi har utviklet V4 fra grunnen for å sikre økt stabilitet, skalerbarhet og fleksibilitet i endringer. Endringer i OpenAPI-spesifikasjonen er også implementert for å forbedre brukervennligheten og forståelsen av APIet.

Overgangsarkitektur​

Som en del av prosjektet 'Digital Drivkraft', oppdaterer vi NVDB-kjernen i en stegvis prosess. NVDB API Les V4 er en integrert del av denne oppdateringen.

I første fase av oppdateringen har V4 hatt tilbakefall til V3. Denne versjonen har vært tilgjengelig siden november 2024, og brukere har fått teste ut migreringen fra V3 til V4. Fra april vil denne versjonen avvikles. URLen vil fortsatt være tilgjengelig, men midlertidig hente direkte fra V3.

I mai er det planlagt en lansering av API LES V4 uten tilbakefall til V3. Deretter vil vi i en periode ha både API LES V3 og API LES V4 operative samtidig. Dette gir brukerne fleksibilitet til å migrere i eget tempo, uten at eksisterende arbeidsflyter og integrasjoner blir brått avbrutt. Det er planlagt å begynne avviklingen av API LES V3 i august, så sett av tid til å gjennomføre migreringen.

Direkte til V4 uten tilbakefall​ til V3​

Selv om den uversjonerte URLen vil midlertidig peke til V3, er det mulig å nå V4 uten tilbakefall til V3 ved å benytte den versjonerte versjonen. Da kan man spesifisere <tjeneste>/api/v4/ i tillegg, for eksempel: 

https://nvdbapiles.atlas.vegvesen.no/vegobjekter/api/v4/vegobjekter/105

Merk at vegobjekter blir brukt to ganger her; første gang som navn på selve tjenesten, andre gang som del av endepunktet.

Merk også at V4 uten tilbakefall til V3 har kjente feil per nå, og at APIet anbefales kun til testbruk frem til den planlagte re-lanseringen i mai.

Den versjonerte versjonen vil også være tilgjengelig senere hvis man for eksempel vil være helt sikker på at det er V4 man benytter.

Migreringsguide​

For å migrere fra NVDB API Les V3 til V4, endre APIets URL:

Fra: 

https://nvdbapiles-v3.atlas.vegvesen.no

til: 

https://nvdbapiles.atlas.vegvesen.no
Flere OpenAPI definisjoner

NVDB API Les V4 tilbyr flere OpenAPI definisjoner.

Se valgmeny øverst til høyre i Swagger UI for å velge ønske definisjon. Følgende er tilgjengelig:

Forskjeller mellom V3 og V4​

  • Data returnert fra V4 vil være tilnærmet identisk med V3 for å sikre bakoverkompatibilitet. Endringer i OpenAPI-spesifikasjonen er imidlertid gjennomført for å reflektere data nøyaktig og forbedre feilhåndteringen.
  • Feil presenteres nå i henhold til RFC 7807 - Problem Details for HTTP APIs.
  • V4 introduserer nye parametere for å tilpasse datauttrekk, som inkluderer muligheten til å utelate sortering og totalt antall objekter med parametrene inkluderAntall og sortert, noe som kan akselerere datahenting.
  • /statistikk endepunktet tillater nå også spesifikasjon av hvilke data som skal inkluderes i responsen.
  • Datatype er ikke i bruk i V4. Den er flagget i Datakatalogen (https://www.vegvesen.no/fag/teknologi/nasjonal-vegdatabank/datakatalogen/) at den vil utgå. I stedet for datatype skal man benytte egenskapstype, geometritype og stedfestingstype. Se denne siden for informasjon om egenskapstype i V4: https://nvdbapiles.atlas.vegvesen.no/webjars/swagger-ui/index.html?urls.primaryName=Datakatalog.
  • Ruteberegning i V4 med geometri oppfører seg slik det var tiltenkt. En geometris punkter styrer hvilke punkter en rute skal gå via, for å komme fra start til slutt. Geometrienes punkter blir projisert ned på på nærmeste veglenke, og punktene bestemmer således hvordan ruten blir. (Gamle V3's oppførsel var slik i starten, den har utilsiktet fått en annen oppførel.)
  • V3 inkluderer informasjon om stedfesting/lokasjon og relasjoner (barn/foreldre) både som egne felt i responsen, og som egenskaper i egenskaper-listen. V4 vil ikke inkludere disse egenskapene, kun feltene under lokasjon og relasjoner. Slik unngås unødig duplisering, og responsen blir mer lik det man sender inn i Skriv API.
  • V3 bruker lokal tid for feltet metadata.sist_modifisert. Dette byr på tvetydighet i overgang mellom sommertid og vintertid. V4 bruker i stedet UTC-tid på ISO 8601-format. Dette betyr at tiden vil ha formatet “2025-04-01T04:48:43Z". Merk en ekstra Z på slutten, som indikerer at dette er UTC-tid.
  • Kartutsnittspørringer i V4 vil som standard bruke en enklere algoritme for å bestemme om et vegobjekt er innenfor kartutsnittet. Spesifikt vil vegobjektets "bounding box” benyttes. Dette gjør at uthentingen blir raskere, men kan medføre at vegobjekter inkluderes der selve vegnettsgeometrien ligger akkurat utenfor kartutsnitt. Ved behov kan det innføres en styringsparameter dersom en trenger nøyaktig presisjon på vegnettsgeometri, eller man kan filtrere ut dette selv etter uthenting.
  • Vegobjekter med foreldre vil bare inkludere foreldre-objekter som har overlappende gyldighet.
  • Vegobjekttype 538 har endret navn fra «gate» til «adresse» i datakatalogen. Områdetjenesten i V3 returnerer fortsatt «gate», men i responsrevisjon 5 til V3 er dette endret til «adresse». I V4 vil områdetjenesten returnere «adresse» under lokasjon. 

Sideoppsett​

I V4 erneste i sideoppsettet endret fra base64-kodet tekst til et variabelt format avhengig av hva slags spørring man gjør. Som konsument trenger man ikke ta stilling til dette, ettersom man uansett benytter “neste”-URL man får fra API.

Fordeler med V4​

  • Økt stabilitet og utviklingsvennlighet
  • Forbedret skalerbarhet
  • Raskere datahenting
  • Færre unødvendige data
  • Raskere implementering av nye funksjoner

Kontakt oss​

For spørsmål, vennligst kontakt oss via e-post: nvdb-api@vegvesen.no