Cilat janë strategjitë kryesore të versioning-ut të API-ve, dhe si e bën deprecate një version?

Question

IT Interview Practice · Accepted Answer

Versioning të lejon të zhvillosh një API me **breaking changes** pa i prishur client-ët ekzistues. Ekzistojnë tri strategji kryesore, plus një proces deprecation.

## Tri strategjitë

**1. URI versioning** — versioni është në path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Më i thjeshti dhe më i dukshmi; i lehtë për të bërë route, cache, dhe test në një browser. E meta: teknikisht shkel "URI-ja identifikon një resource" (i njëjti user tani ka dy URL). Kjo është me diferencë zgjedhja më e zakonshme (GitHub, Stripe historikisht).

**2. Custom header versioning** — versioni udhëton në një header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
I mban URL-të të pastra por është i padukshëm në një browser dhe më i vështirë për t'u cache-uar.

**3. Media-type (content negotiation) versioning** — versioni në `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Më "RESTful"-i (URL-ja e resource-it është e qëndrueshme; vetëm representation-i i tij versionohet), por më pak i afrueshmi për konsumatorët.

## Çfarë numërohet si 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*
```
Vetëm breaking changes kanë nevojë për një version të ri; shto non-breaking changes te versioni aktual.

## Procesi i deprecation

1. **Njofto** me data në docs dhe changelog.
2. **Sinjalizo në runtime** me headers që client-ët ta vënë re në mënyrë programatike:
```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. **Monitoro** përdorimin e versionit të vjetër dhe kontakto thirrësit e mbetur.
4. **Sunset** vetëm pasi përdorimi të bjerë afër zeros.

## Pse ka rëndësi

Intervistuesit e pyesin këtë për të parë nëse mund ta rritësh një API në production pa i prishur client-ët që varen prej tij — një shqetësim real operacional, jo teorik. Përgjigjet më të forta bëjnë dy dallime: së pari, se **shumica e ndryshimeve janë non-breaking** dhe nuk duhet të shkaktojnë fare një ngritje versioni (ndryshimet shtuese futen te versioni aktual), duke e rezervuar versioning-un për breaking changes vërtet të tilla; dhe së dyti, se *strategjia* ka më pak rëndësi se *procesi* — një afat i qartë deprecation me headers `Deprecation`/`Sunset` dhe monitorim përdorimi është ajo që i mbron realisht konsumatorët. URI versioning fiton në praktikë për dukshmërinë dhe mbështetjen nga tooling, por të njohësh kompromiset (header dhe media-type i mbajnë URL-të të qëndrueshme dhe janë më RESTful, me koston e zbulueshmërisë) tregon se e kupton hapësirën e dizajnit sesa thjesht të ndjekësh verbërisht `/v1/`.

Tri strategjitë

Çfarë numërohet si breaking

Procesi i deprecation

Pse ka rëndësi

Pyetje të ngjashme