Versjonering
API-et bruker semantisk versjonering (SemVer), på formatet: v<MAJOR>.<MINOR>.<PATCH>.
- MAJOR versjon når API-et får brekkende endringer (ikke bakoverkompatibelt).
- MINOR versjon når det legges til funksjonalitet på en bakoverkompatibel måte.
- PATCH versjon når små feilrettinger eller mindre endringer gjøres uten å bryte bakoverkompatibilitet.
Bakoverkompabilitet
Vi etterstreber å forbedre API-ene våres på en bakoverkompatibel måte der det er mulig.
For å gjøre det tydelig hva dere kan forvente fra API-et og hva vi forventer av dere som konsument, gis noen eksempler på hva vi anser som brekkende og ikke-brekkende endringer.
Bakoverkompatible endringer(ny MINOR eller PATCH):
Se de respektive API-sidene for detaljer om hvordan hvert API forholder seg til bakoverkompatible endringer:
Brekkende endringer (ny MAJOR):
- Endre navngiving på felter
- Fjerne et endepunkt
- Fjerne et påkrevd felt i respons/request
- Et felt i responsen går fra å være påkrevd til å være valgfritt
- Endre eller fjerne feilkoder
- Gjøre et valgfritt felt i request påkrevd
- Endre datatype på et felt i responsen
- Restrukturere hierarkiet i responsen
I situasjoner hvor det blir nødvendig å gjøre brekkende endringer, vil vi beholde gamle API-er i henhold til gjeldende avtale.
I en periode vil det altså være mulig å hente ressurser fra flere versjoner, for eksempel URLene hos Bygning for uthenting av egenregistrert data er /bygning/v1/virksomhet_begrenset/... og kan deretter bli, /bygning/v2/virksomhet_begrenset/....