X'inhuma l-istrateġiji ewlenin tal-versioning tal-API, u kif tiddeprekja verżjoni?

Question

IT Interview Practice · Accepted Answer

Il-versioning iħallik tevolvi API b'**breaking changes** mingħajr ma tkisser il-clients eżistenti. Hemm tliet strateġiji ewlenin, flimkien ma' proċess ta' deprekazzjoni.

## It-tliet strateġiji

**1. URI versioning** — il-verżjoni tinsab fil-path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
L-aktar sempliċi u viżibbli; faċli biex tagħmel routing, cache, u test fil-browser. Żvantaġġ: teknikament tikser "l-URI jidentifika resource" (l-istess user issa għandu żewġ URLs). Din hija bil-bosta l-aktar għażla komuni (GitHub, Stripe storikament).

**2. Custom header versioning** — il-verżjoni tivvjaġġa f'header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Iżomm l-URLs nodfa imma huwa inviżibbli fil-browser u aktar diffiċli biex tagħmel cache.

**3. Media-type (content negotiation) versioning** — il-verżjoni f'`Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
L-aktar "RESTful" (l-URL tar-resource huwa stabbli; hija biss ir-representation tiegħu li tiġi versioned), imma l-anqas aċċessibbli għall-konsumaturi.

## X'jgħodd bħala 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*
```
Il-breaking changes biss jeħtieġu verżjoni ġdida; żid il-bidliet non-breaking ma' dik kurrenti.

## Proċess ta' deprekazzjoni

1. **Ħabbar** bid-dati fid-docs u fil-changelog.
2. **Issenjala fil-ħin (runtime)** b'headers biex il-clients jinnutaw b'mod programmatiku:
```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. **Immonitorja** l-użu tal-verżjoni l-antika u ikkuntattja lill-callers li fadal.
4. **Sunset** biss wara li l-użu jinżel qrib iż-żero.

## Għaliex huwa importanti

L-intervistaturi jistaqsu dan biex jaraw jekk tistax tkabbar API fil-produzzjoni mingħajr ma tkisser il-clients li jiddependu fuqha — kunċern operazzjonali reali, mhux wieħed teoretiku. L-aktar tweġibiet b'saħħithom jagħmlu żewġ distinzjonijiet: l-ewwel, li **ħafna bidliet huma non-breaking** u m'għandhomx jiskattaw bump tal-verżjoni (il-bidliet additivi jidħlu fil-verżjoni kurrenti), u jżommu l-versioning għal breaking changes ġenwini; u t-tieni, li l-*istrateġija* timporta anqas mill-*proċess* — timeline ċara ta' deprekazzjoni b'headers `Deprecation`/`Sunset` u monitoraġġ tal-użu huwa dak li verament jipproteġi lill-konsumaturi. Il-URI versioning tirbaħ fil-prattika għall-viżibbiltà u s-sostenn tat-tooling tagħha, imma li tkun taf it-trade-offs (l-header u l-media-type iżommu l-URLs stabbli u huma aktar RESTful, bl-ispiża tal-iskopribbiltà) juri li tifhem l-ispazju tad-disinn aktar milli sempliċiment tikkopja `/v1/`.

It-tliet strateġiji

X'jgħodd bħala breaking

Proċess ta' deprekazzjoni

Għaliex huwa importanti

Mistoqsijiet relatati