Koje su glavne strategije versioninga API-ja i kako deprecirati verziju?

Question

IT Interview Practice · Accepted Answer

Versioning vam omogućuje razvoj API-ja s **breaking promjenama** bez rušenja postojećih klijenata. Postoje tri glavne strategije, plus proces depreciranja.

## Tri strategije

**1. URI versioning** — verzija je u putanji.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Najjednostavniji i najvidljiviji; lako za routing, cachiranje i testiranje u pregledniku. Nedostatak: tehnički krši "URI identificira resurs" (isti korisnik sada ima dva URL-a). Ovo je daleko najčešći izbor (GitHub, Stripe povijesno).

**2. Custom header versioning** — verzija putuje u headeru.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Drži URL-ove čistima, ali je nevidljiv u pregledniku i teži za cachiranje.

**3. Media-type (content negotiation) versioning** — verzija u `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Najviše "RESTful" (URL resursa je stabilan; samo se njegova reprezentacija verzionira), ali najmanje pristupačan potrošačima.

## Što se računa kao breaking

```text
BREAKING      → uklanjanje/preimenovanje polja, promjena tipa, promjena autha, pooštravanje validacije
NON-BREAKING  → dodavanje novog opcionalnog polja, dodavanje novog endpointa, dodavanje enum vrijednosti*
```
Samo breaking promjene trebaju novu verziju; non-breaking promjene dodajte u trenutnu.

## Proces depreciranja

1. **Najavite** s datumima u dokumentaciji i changelogu.
2. **Signalizirajte u runtimeu** headerima kako bi klijenti primijetili programski:
```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. **Pratite** upotrebu stare verzije i kontaktirajte preostale pozivatelje.
4. **Sunset** tek nakon što upotreba padne blizu nule.

## Zašto je to važno

Ispitivači ovo pitaju kako bi vidjeli možete li razvijati API u produkciji bez rušenja klijenata koji o njemu ovise — stvarna operativna briga, ne teoretska. Najsnažniji odgovori prave dvije razlike: prvo, da je **većina promjena non-breaking** i ne bi uopće trebala pokretati skok verzije (aditivne promjene idu u trenutnu verziju), rezervirajući versioning za istinski breaking promjene; i drugo, da *strategija* znači manje od *procesa* — jasna vremenska crta depreciranja s `Deprecation`/`Sunset` headerima i praćenjem upotrebe ono je što zapravo štiti potrošače. URI versioning pobjeđuje u praksi zbog svoje vidljivosti i podrške alata, ali poznavanje kompromisa (header i media-type drže URL-ove stabilnima i RESTful-ijima su, po cijenu otkrivljivosti) pokazuje da razumijete prostor dizajna, a ne samo slijepo kopirate `/v1/`.

Tri strategije

Što se računa kao breaking

Proces depreciranja

Zašto je to važno

Povezana pitanja