Mik a fő API-versioning stratégiák, és hogyan deprecate-elsz egy verziót?

Question

IT Interview Practice · Accepted Answer

A versioning lehetővé teszi egy API továbbfejlesztését **breaking change**-ekkel a meglévő kliensek megtörése nélkül. Három fő stratégia van, plusz egy deprecation-folyamat.

## A három stratégia

**1. URI versioning** — a verzió a path-ban van.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
A legegyszerűbb és leglátványosabb; könnyen routolható, cache-elhető és böngészőben tesztelhető. Hátrány: technikailag megsérti azt, hogy "az URI azonosítja az erőforrást" (ugyanannak a usernek most két URL-je van). Ez messze a leggyakoribb választás (GitHub, korábban a Stripe).

**2. Custom header versioning** — a verzió egy headerben utazik.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Tisztán tartja az URL-eket, de láthatatlan a böngészőben, és nehezebben cache-elhető.

**3. Media-type (content negotiation) versioning** — a verzió az `Accept`-ben.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
A leginkább "RESTful" (az erőforrás URL-je stabil; csak a reprezentációja verziózott), de a felhasználók számára a legkevésbé megközelíthető.

## Mi számít breakingnek

```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*
```
Csak a breaking change-ek igényelnek új verziót; a non-breaking változtatásokat a jelenlegihez add hozzá.

## Deprecation-folyamat

1. **Jelentsd be** dátumokkal a dokumentációban és a changelogban.
2. **Jelezd futásidőben** headerekkel, hogy a kliensek programozottan észrevegyék:
```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. **Monitorozd** a régi verzió használatát, és keresd meg a megmaradt hívókat.
4. **Sunset** (kivezetés) csak azután, hogy a használat közel nullára esik.

## Miért fontos

Az interjúztatók azért kérdezik ezt, hogy lássák, tudsz-e egy API-t éles környezetben növelni anélkül, hogy megtörnéd a rá támaszkodó klienseket — valós üzemeltetési gond, nem elméleti. A legerősebb válaszok két megkülönböztetést tesznek: először, hogy **a legtöbb változás non-breaking**, és egyáltalán nem szabad verzióemelést kiváltania (a bővítő változtatások a jelenlegi verzióba kerülnek), a versioningot a valóban breaking change-ekre tartva fenn; másodszor, hogy a *stratégia* kevésbé számít, mint a *folyamat* — egy világos deprecation-ütemterv `Deprecation`/`Sunset` headerekkel és használat-monitorozással az, ami ténylegesen megvédi a felhasználókat. Az URI versioning nyer a gyakorlatban a láthatósága és tooling-támogatása miatt, de a kompromisszumok ismerete (a header és a media-type stabilan tartja az URL-eket és RESTful-abb, a felfedezhetőség árán) azt mutatja, hogy érted a tervezési teret, nem csak vakon másolod a `/v1/`-et.

A három stratégia

Mi számít breakingnek

Deprecation-folyamat

Miért fontos

Kapcsolódó kérdések