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 i utviklingsmiljøet og testmiljøet. URLene vil fortsatt være tilgjengelige, men peke på API LES V4 uten tilbakefalll til V3, som er siste og nyeste versjon av API LES V4.

I mai er det planlagt en lansering av API LES V4 uten tilbakefall til V3 i produksjonsmiljøet. Systemet overtar for API LES V3 med tilbakefall til V3, som da vil være avviklet i alle miljø, både versjonert og uversjonert. 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.

Versjonert tjeneste - direkte til V4​

Versjonert tjeneste er i produksjon i to versjoner. Ved for eksempel behov for å være helt sikker på at man går mot V4, 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.

Dette er per nå V4 med tilbakefall til V3. Det er også mulig å nå V4 uten tilbakefall til V3 ved å benytte den versjonerte-blue versjonen:

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

Merk at V4 uten tilbakefall til V3 er i akseptansetest, og APIet anbefales kun til testbruk. Under den planlagte lanseringen i mai vil dette endepunktet forsvinne.

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.
  • relasjoner har et nytt felt relasjonstype, som kan være enten vegobjekter eller vegobjektIder. Dette gjør desarialisering enklere i tilfeller hvor man sender med dybde > 1.
  • Parameter sluttDato for endepunktet /vegobjekt endres til tidspunkt.
  • Parameter arm fjernes for alle vegobjekt-endepunkt, da det ikke var i bruk. Det er fremdeles til stede for vegnett.
  • V4 introduserer et nytt felt geometrimål som gir geometrilengde/areal for objekter med egengeometri av type LINESTRING eller POLYGON.
  • Den ukentlige fullindekseringen utgår i V4.
  • Status UTFØRT_OG_ETTERBEHANDLET utgår i V4.
  • status-endepunktet utgår i V4.
  • transaksjoner-endepunktet utgår i V4, men erstattes av tilsvarende funksjonalitet på nye endepunkt.
  • I geometrikvalitet mappes målemetodeHøyde -1 til datafangstmetodeHøyde "ukj", og alle -1-verdier på høydeparametre skjules i V4.
  • V4 introduserer et nytt filtreringsparameter Vegforvalter for vegobjekt og vegnett.
  • V4 introdusererer en ny node metrertLokasjon under "Lokasjon/Vegsystemreferanse" som angir stedfestet retning, stedfestet sideposisjon og kjøreretning.
  • I V4 filtreres ugyldige foreldre bort ved å kreve overlapp i tid for foreldre og barn.

Sideoppsett​

I V4 er neste 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