Apakah strategi versioning API utama, dan bagaimana anda men-deprecate sesuatu versi?

Question

IT Interview Practice · Accepted Answer

Versioning membolehkan anda mengembangkan API dengan **breaking change** tanpa merosakkan client sedia ada. Terdapat tiga strategi arus perdana, serta satu proses deprecation.

## Tiga strategi

**1. URI versioning** — versi berada dalam path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Paling ringkas dan paling nyata; mudah untuk route, cache, dan uji dalam pelayar. Keburukan: secara teknikal ia melanggar "URI mengenal pasti sumber" (user yang sama kini mempunyai dua URL). Ini setakat ini pilihan paling lazim (GitHub, Stripe secara sejarah).

**2. Custom header versioning** — versi bergerak dalam header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Mengekalkan URL bersih tetapi tidak kelihatan dalam pelayar dan lebih sukar di-cache.

**3. Media-type (content negotiation) versioning** — versi dalam `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Paling "RESTful" (URL sumber stabil; hanya representasinya di-version), tetapi paling sukar didekati oleh pengguna.

## Apa yang dikira 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*
```
Hanya breaking change memerlukan versi baharu; tambah perubahan non-breaking ke versi semasa.

## Proses deprecation

1. **Umumkan** dengan tarikh dalam dokumentasi dan changelog.
2. **Beri isyarat semasa runtime** dengan header supaya client perasan secara aturcara:
```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. **Pantau** penggunaan versi lama dan hubungi pemanggil yang masih tinggal.
4. **Sunset** hanya selepas penggunaan jatuh menghampiri sifar.

## Mengapa ia penting

Penemu duga bertanya ini untuk melihat sama ada anda boleh mengembangkan API dalam production tanpa merosakkan client yang bergantung padanya — kebimbangan operasi sebenar, bukan teori. Jawapan paling kukuh membuat dua perbezaan: pertama, bahawa **kebanyakan perubahan adalah non-breaking** dan tidak sepatutnya mencetuskan lonjakan versi langsung (perubahan tambahan masuk ke versi semasa), menyimpan versioning untuk breaking change yang benar-benar; dan kedua, bahawa *strategi* kurang penting berbanding *proses* — garis masa deprecation yang jelas dengan header `Deprecation`/`Sunset` dan pemantauan penggunaan itulah yang sebenarnya melindungi pengguna. URI versioning menang dalam praktik kerana kenampakan dan sokongan tooling-nya, tetapi mengetahui trade-off (header dan media-type mengekalkan URL stabil dan lebih RESTful, dengan kos keboleh-temuan) menunjukkan anda memahami ruang reka bentuk dan bukan sekadar meniru `/v1/`.

Tiga strategi

Apa yang dikira breaking

Proses deprecation

Mengapa ia penting

Soalan berkaitan