Hvad er de vigtigste API-versioneringsstrategier, og hvordan udfaser (deprecate) du en version?

Question

IT Interview Practice · Accepted Answer

Versionering lader dig videreudvikle en API med **breaking changes** uden at ødelægge eksisterende clients. Der er tre gængse strategier plus en deprecation-proces.

## De tre strategier

**1. URI-versionering** — versionen er i path'en.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Enklest og mest synlig; let at route, cache og teste i en browser. Ulempe: det bryder teknisk set med "URI'en identificerer en resource" (den samme user har nu to URL'er). Dette er langt det mest almindelige valg (GitHub, Stripe historisk set).

**2. Custom header-versionering** — versionen rejser i en header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Holder URL'er rene, men er usynlig i en browser og sværere at cache.

**3. Media-type- (content negotiation-)versionering** — version i `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Den mest "RESTful" (resource-URL'en er stabil; kun dens representation versioneres), men den mindst tilgængelige for forbrugere.

## Hvad tæller som breaking

```text
BREAKING      → fjern/omdøb et felt, ændr en type, ændr auth, stram validering
NON-BREAKING  → tilføj et nyt valgfrit felt, tilføj et nyt endpoint, tilføj en enum-værdi*
```
Kun breaking changes kræver en ny version; tilføj non-breaking changes til den nuværende.

## Deprecation-proces

1. **Annoncér** med datoer i dokumentation og changelog.
2. **Signalér ved runtime** med headers, så clients bemærker 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åg** brugen af den gamle version og kontakt de tilbageværende kaldere.
4. **Sunset** først, når brugen falder til nær nul.

## Hvorfor det betyder noget

Interviewere spørger om dette for at se, om du kan udvikle en API i produktion uden at ødelægge de clients, der afhænger af den — en reel driftsmæssig bekymring, ikke en teoretisk. De stærkeste svar laver to skel: for det første, at **de fleste ændringer er non-breaking** og slet ikke bør udløse en versionsopdatering (additive ændringer går ind i den nuværende version), og reserverer versionering til reelt breaking changes; og for det andet, at *strategien* betyder mindre end *processen* — en klar deprecation-tidslinje med `Deprecation`/`Sunset`-headers og brugsovervågning er det, der faktisk beskytter forbrugerne. URI-versionering vinder i praksis på grund af sin synlighed og tooling-understøttelse, men at kende afvejningerne (header og media-type holder URL'er stabile og er mere RESTful, på bekostning af opdagelighed) viser, at du forstår designrummet frem for bare at cargo-culte `/v1/`.

De tre strategier

Hvad tæller som breaking

Deprecation-proces

Hvorfor det betyder noget

Relaterede spørgsmål