Apa saja strategi API versioning utama, dan bagaimana Anda men-deprecate sebuah versi?

Question

IT Interview Practice · Accepted Answer

Versioning memungkinkan Anda mengembangkan sebuah API dengan **breaking change** tanpa merusak client yang sudah ada. Ada tiga strategi arus utama, plus sebuah proses deprecation.

## Tiga strategi

**1. URI versioning** — versi berada di path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Paling sederhana dan paling terlihat; mudah untuk di-route, di-cache, dan diuji di browser. Kekurangannya: secara teknis ia melanggar "URI mengidentifikasi sebuah resource" (user yang sama kini punya dua URL). Ini sejauh ini pilihan yang paling umum (GitHub, Stripe secara historis).

**2. Custom header versioning** — versi berjalan dalam sebuah header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Menjaga URL tetap bersih tetapi tidak terlihat di browser dan lebih sulit di-cache.

**3. Media-type (content negotiation) versioning** — versi di `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Yang paling "RESTful" (URL resource stabil; hanya representasinya yang di-versi), tetapi paling tidak mudah didekati oleh konsumen.

## Apa yang dihitung sebagai 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 yang membutuhkan versi baru; tambahkan perubahan non-breaking ke versi saat ini.

## Proses deprecation

1. **Umumkan** dengan tanggal di dokumentasi dan changelog.
2. **Beri sinyal saat runtime** dengan header agar client menyadarinya secara programatik:
```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 caller yang tersisa.
4. **Sunset** hanya setelah penggunaan turun mendekati nol.

## Mengapa ini penting

Pewawancara menanyakan ini untuk melihat apakah Anda bisa menumbuhkan sebuah API di produksi tanpa merusak client yang bergantung padanya — kekhawatiran operasional nyata, bukan teoretis. Jawaban terkuat membuat dua pembedaan: pertama, bahwa **sebagian besar perubahan bersifat non-breaking** dan tidak seharusnya memicu bump versi sama sekali (perubahan aditif masuk ke versi saat ini), menyisakan versioning untuk breaking change yang benar-benar terjadi; dan kedua, bahwa *strategi* kurang penting dibanding *proses* — timeline deprecation yang jelas dengan header `Deprecation`/`Sunset` dan pemantauan penggunaan adalah yang sebenarnya melindungi konsumen. URI versioning menang dalam praktik karena keterlihatan dan dukungan tooling-nya, tetapi mengetahui trade-off-nya (header dan media-type menjaga URL tetap stabil dan lebih RESTful, dengan mengorbankan discoverability) menunjukkan Anda memahami ruang desain alih-alih sekadar meniru `/v1/` secara membabi buta.

Tiga strategi

Apa yang dihitung sebagai breaking

Proses deprecation

Mengapa ini penting

Pertanyaan terkait