Hva er de viktigste strategiene for API-versjonering, og hvordan deprekerer du en versjon?

Question

IT Interview Practice · Accepted Answer

Versjonering lar deg videreutvikle et API med **breaking changes** uten å ødelegge for eksisterende klienter. Det finnes tre hovedstrategier, pluss en deprekeringsprosess.

## De tre strategiene

**1. URI-versjonering** — versjonen er i pathen.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Enklest og mest synlig; lett å rute, cache og teste i en nettleser. Ulempe: det bryter teknisk sett med "URI-en identifiserer en ressurs" (samme user har nå to URL-er). Dette er det klart vanligste valget (GitHub, Stripe historisk).

**2. Egendefinert header-versjonering** — versjonen følger med i en header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Holder URL-er rene, men er usynlig i en nettleser og vanskeligere å cache.

**3. Media-type- (content negotiation-)versjonering** — versjon i `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Den mest "RESTful" (ressurs-URL-en er stabil; bare representasjonen versjoneres), men den minst tilgjengelige for konsumenter.

## Hva som teller som breaking

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
Bare breaking changes trenger en ny versjon; legg non-breaking changes til den gjeldende.

## Deprekeringsprosess

1. **Kunngjør** med datoer i dokumentasjon og changelog.
2. **Signalér ved kjøretid** med headere slik at klienter merker det programmatisk:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Overvåk** bruken av den gamle versjonen og ta kontakt med gjenværende kallere.
4. **Sunset** først etter at bruken faller mot null.

## Hvorfor det er viktig

Intervjuere spør om dette for å se om du kan la et API vokse i produksjon uten å ødelegge for klientene som avhenger av det — et reelt driftshensyn, ikke et teoretisk. De sterkeste svarene gjør to skillelinjer: for det første at **de fleste endringer er non-breaking** og ikke bør utløse et versjonshopp i det hele tatt (additive endringer går inn i den gjeldende versjonen), og reserverer versjonering for genuint breaking changes; og for det andre at *strategien* betyr mindre enn *prosessen* — en tydelig deprekeringstidslinje med `Deprecation`/`Sunset`-headere og bruksovervåking er det som faktisk beskytter konsumentene. URI-versjonering vinner i praksis på grunn av synligheten og verktøystøtten, men å kjenne avveiingene (header og media-type holder URL-er stabile og er mer RESTful, på bekostning av oppdagbarhet) viser at du forstår designrommet snarere enn bare å etterape `/v1/`.

De tre strategiene

Hva som teller som breaking

Deprekeringsprosess

Hvorfor det er viktig

Relaterte spørsmål