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
Versjonen av API‑et angis i URL‑en:
/api/v3/<scope>/<method-name>
der <scope> er enten full-access eller restricted-access, og <method-name> er delen av API‑et, for eksempel person, event eller search.
Eksempel:
GET /api/v3/full-access/person/12345678910
api-version i HTTP‑headeren er ikke nødvendig, siden versjonen allerede er angitt i URL‑en.
Versjon 2 og tidligere
Versjon 2 og versjon 1 er fjernet. Støtte for eldre versjoner av API‑et ble permanent avsluttet 05.05.2026, og kun versjon 3 er tilgjengelig.
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.
Hva som endret seg i versjon 3
Versjon 3 introduserte brytende endringer sammenlignet med versjon 2:
- Nytt URL‑format for endepunkter:
/api/v3/<scope>/<method-name>(erstatter/api/<scope>/<method-name>) - DPoP‑autentisering er obligatorisk. Se: DPoP‑autentiseringsguide
- Nye scopes:
nhn:hgd-persontjenesten-api/full-accessognhn:hgd-persontjenesten-api/restricted-access, som erstatternhn:hgd-persontjenesten-api/read-with-legal-basisognhn:hgd-persontjenesten-api/read-no-legal-basis - Tomme felter (null‑verdier) utelates fra svaret
Se Changelog for flere detaljer om andre endringer.