API‑versjonering for Person‑API

Person‑API følger prinsippene for semantisk versjonering med et Major.Minor‑skjema. Selv om vi kontinuerlig ruller ut ny funksjonalitet, håndteres bruddende endringer nøye gjennom versjonskontroll. Alle endringer er dokumentert i Changelog.

Legacy‑versjoner er tilgjengelige i 6 måneder etter at de har blitt avviklet.

Versjonsvalg

Versjon 3

I versjon 3 bruker du nye URL‑er for å velge versjon. Det er valgfritt å sette api-version i HTTP‑headeren for versjon 3.

Versjon ≤ 2

For å målrette en spesifikk API‑versjon 2 eller lavere, inkluder api-version‑headeren i forespørselen:

api-version: 2

Hvis ingen versjon angis, vil forespørselen bruke den nyeste tilgjengelige versjonen. Dette gjelder også i en kort overgangsperiode rett etter en bruddende endring.

Versjonstyper

Store versjoner (brytende endringer)

En økning i hovedversjon (X.0) indikerer bruddende endringer som krever oppdatering hos klienten. Eksempler inkluderer:

• Betydelige endringer i informasjonsmodellen
• Tekniske korrigeringer
• Oppdateringer i infrastrukturen
• Sikkerhetsforbedringer

Når vi slipper en ny hovedversjon:

• Begge versjonene kjører parallelt i overgangsperioden
• Klienter har 6 måneder på seg til å migrere til den nye versjonen
• Det gis klare migrasjonsveiledninger

Små versjoner (ikke‑brytende endringer)

En økning i mindre versjon (1.X) indikerer bakoverkompatible endringer, for eksempel:

• Nye endepunkter
• Ekstra datafelter
• Valgfrie parametere
• Forbedret funksjonalitet

Eksisterende integrasjoner fortsetter å fungere uten endringer, selv om oppdateringer kan være nødvendig for å ta i bruk de nye funksjonene.

Migrasjonsretningslinjer

Migrering fra versjon 2 til versjon 3

Obligatoriske endringer:

1. Oppdater API versjon header (eller fjern det, det er valgfritt i v3):

   api-version: 3
   

2. Bruk oppdaterte endepunkt URLs:

   • Ny format: /api/v3/<scope>/<method-name>
   • Gammelt format: /api/<scope>/<method-name>

3. Oppdater autentisering:

   • Implementer DPoP‑autentisering
   • Se: DPoP‑autentiseringsguide

4. Oppdater scopes:

   • Ny: full-access og restricted-access
   • Erstatter: legal-basis og no-legal-basis

5. Se Endringslogg for flere detaljer om andre endringer.

   
   **Merk:** Versjon 2 vil bli deaktivert 15.04.2026 i produksjon og 12.03.2026 i test.