Mbinu kuu za versioning ya API ni zipi, na unai-deprecate version vipi?

Question

IT Interview Practice · Accepted Answer

Versioning hukuwezesha kuendeleza API kwa **breaking changes** bila kuvunja clients zilizopo. Kuna mbinu kuu tatu, pamoja na mchakato wa deprecation.

## Mbinu tatu

**1. URI versioning** — version iko katika path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Rahisi zaidi na inayoonekana zaidi; rahisi ku-route, ku-cache, na ku-test katika kivinjari. Upungufu: kitaalamu inakiuka "URI hutambua rasilimali" (user yule yule sasa ana URLs mbili). Hili ndilo chaguo la kawaida zaidi kwa mbali (GitHub, Stripe kihistoria).

**2. Custom header versioning** — version husafiri katika header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Huweka URLs safi lakini haionekani katika kivinjari na ni ngumu zaidi ku-cache.

**3. Media-type (content negotiation) versioning** — version katika `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Yenye "RESTful" zaidi (URL ya rasilimali ni thabiti; representation yake pekee ndiyo ime-versioned), lakini isiyofikika zaidi kwa watumiaji.

## Nini huhesabika kama 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*
```
Breaking changes pekee zinahitaji version mpya; ongeza non-breaking changes kwenye ile ya sasa.

## Mchakato wa deprecation

1. **Tangaza** kwa tarehe katika docs na changelog.
2. **Ashiria wakati wa runtime** kwa headers ili clients zitambue kiprogramu:
```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. **Fuatilia** matumizi ya version ya zamani na wasiliana na callers waliobaki.
4. **Sunset** tu baada ya matumizi kushuka karibu na sifuri.

## Kwa nini ni muhimu

Wahoji huuliza hili kuona kama unaweza kukuza API katika production bila kuvunja clients zinazoitegemea — jambo halisi la kiuendeshaji, si la kinadharia. Majibu imara zaidi hufanya tofauti mbili: kwanza, kwamba **mabadiliko mengi ni non-breaking** na hayapaswi kuchochea version bump hata kidogo (mabadiliko ya nyongeza huingia katika version ya sasa), yakihifadhi versioning kwa breaking changes za kweli; na pili, kwamba *mbinu* haina umuhimu kama *mchakato* — ratiba wazi ya deprecation yenye headers za `Deprecation`/`Sunset` na ufuatiliaji wa matumizi ndiyo hasa inayolinda watumiaji. URI versioning hushinda kivitendo kwa kuonekana kwake na msaada wa tooling, lakini kujua trade-offs (header na media-type huweka URLs thabiti na ni RESTful zaidi, kwa gharama ya ugunduzi) huonyesha unaelewa nafasi ya usanifu badala ya kunakili tu `/v1/`.

Mbinu tatu

Nini huhesabika kama breaking

Mchakato wa deprecation

Kwa nini ni muhimu

Maswali yanayohusiana