Katere so glavne strategije versioninga API-jev in kako deprecirate verzijo?

Question

IT Interview Practice · Accepted Answer

Versioning omogoča razvoj API-ja z **breaking changes**, ne da bi pokvarili obstoječe odjemalce. Obstajajo tri glavne strategije, plus proces depreciacije.

## Tri strategije

**1. URI versioning** — verzija je v poti.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Najpreprostejši in najbolj viden; enostaven za usmerjanje, predpomnjenje in testiranje v brskalniku. Slabost: tehnično krši "URI identificira vir" (isti uporabnik ima zdaj dva URL-ja). To je daleč najpogostejša izbira (GitHub, Stripe v preteklosti).

**2. Custom header versioning** — verzija potuje v glavi.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Ohrani URL-je čiste, a je neviden v brskalniku in težji za predpomnjenje.

**3. Media-type (content negotiation) versioning** — verzija v `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Najbolj "RESTful" (URL vira je stabilen; verzionira se le njegova predstavitev), a najmanj dostopen za uporabnike.

## Kaj šteje kot 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*
```
Le breaking changes potrebujejo novo verzijo; non-breaking spremembe dodajte v trenutno.

## Proces depreciacije

1. **Napovej** z datumi v dokumentaciji in changelogu.
2. **Signaliziraj ob izvajanju** z glavami, da odjemalci to opazijo programsko:
```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. **Spremljaj** rabo stare verzije in stopi v stik s preostalimi klicatelji.
4. **Sunset** šele, ko raba pade blizu nič.

## Zakaj je to pomembno

Spraševalci to sprašujejo, da vidijo, ali znate API v produkciji razvijati, ne da bi pokvarili odjemalce, ki so od njega odvisni — resnična operativna skrb, ne teoretična. Najmočnejši odgovori naredijo dve razlikovanji: prvič, da je **večina sprememb non-breaking** in sploh ne bi smela sprožiti dviga verzije (aditivne spremembe gredo v trenutno verzijo), versioning pa se prihrani za resnično breaking spremembe; in drugič, da je *strategija* manj pomembna kot *proces* — jasna časovnica depreciacije z glavama `Deprecation`/`Sunset` in spremljanje rabe je tisto, kar dejansko ščiti uporabnike. URI versioning v praksi zmaga zaradi vidnosti in podpore orodij, a poznavanje kompromisov (header in media-type ohranjata URL-je stabilne in sta bolj RESTful, za ceno odkrivljivosti) pokaže, da razumete prostor zasnove in ne le posnemate `/v1/`.

Tri strategije

Kaj šteje kot breaking

Proces depreciacije

Zakaj je to pomembno

Povezana vprašanja