Vilka är de huvudsakliga API-versioning-strategierna, och hur deprecerar du en version?

Question

IT Interview Practice · Accepted Answer

Versioning låter dig utveckla ett API med **breaking changes** utan att bryta befintliga clients. Det finns tre etablerade strategier, plus en deprecation-process.

## De tre strategierna

**1. URI versioning** — versionen finns i path:en.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Enklast och mest synlig; lätt att routa, cacha och testa i en webbläsare. Nackdel: den bryter tekniskt sett mot "URI:n identifierar en resurs" (samma user har nu två URL:er). Detta är det överlägset vanligaste valet (GitHub, Stripe historiskt).

**2. Custom header versioning** — versionen färdas i en header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Håller URL:er rena men är osynlig i en webbläsare och svårare att cacha.

**3. Media-type (content negotiation) versioning** — version i `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Den mest "RESTful" (resurs-URL:en är stabil; bara dess representation versioneras), men den minst lättillgängliga för konsumenter.

## Vad som räknas som breaking

```text
BREAKING      → ta bort/byt namn på ett fält, ändra en typ, ändra auth, skärp validering
NON-BREAKING  → lägg till ett nytt valfritt fält, lägg till en ny endpoint, lägg till ett enum-värde*
```
Bara breaking changes behöver en ny version; lägg icke-breaking-ändringar till den nuvarande.

## Deprecation-process

1. **Annonsera** med datum i dokumentation och changelog.
2. **Signalera vid runtime** med headers så att clients märker det programmatiskt:
```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. **Övervaka** användning av den gamla versionen och nå ut till kvarvarande anropare.
4. **Sunset** först efter att användningen fallit nära noll.

## Varför det är viktigt

Intervjuare frågar detta för att se om du kan växa ett API i produktion utan att bryta de clients som är beroende av det — en verklig driftsfråga, inte en teoretisk. De starkaste svaren gör två distinktioner: först, att **de flesta ändringar är icke-breaking** och inte alls bör utlösa en version-bump (additiva ändringar går in i den nuvarande versionen), och reserverar versioning för genuint breaking changes; och för det andra, att *strategin* spelar mindre roll än *processen* — en tydlig deprecation-tidslinje med `Deprecation`/`Sunset`-headers och användningsövervakning är vad som faktiskt skyddar konsumenter. URI versioning vinner i praktiken för sin synlighet och verktygsstöd, men att känna till avvägningarna (header och media-type håller URL:er stabila och är mer RESTful, till priset av upptäckbarhet) visar att du förstår designutrymmet snarare än att bara cargo-culta `/v1/`.

De tre strategierna

Vad som räknas som breaking

Deprecation-process

Varför det är viktigt

Relaterade frågor