API Versioning: Mengubah API Tanpa Merusak Klien Lama

Edisi revisi buku pelajaran

Buku pelajaran edisi 2020 dan edisi 2024 bisa berbeda isi, tapi keduanya tetap beredar. Siswa lama memakai edisi lama sampai lulus, siswa baru memakai edisi baru. API versioning menerapkan ide yang sama: saat API berubah secara tidak kompatibel, versi lama tetap hidup untuk klien lama sementara klien baru memakai versi baru.

Kenapa versioning tidak bisa dihindari

API yang dipakai aplikasi mobile tidak bisa dipaksa update serentak: selalu ada user dengan aplikasi versi lama. Tanpa versioning, setiap perubahan response berisiko merusak aplikasi yang sudah terinstall di jutaan HP. Versioning memberi masa transisi yang aman: umumkan versi baru, beri waktu migrasi, lalu pensiunkan versi lama.

Contoh 1: versioning lewat URL path

GET /api/v1/produk/1 HTTP/1.1
Host: toko.contoh.id

GET /api/v2/produk/1 HTTP/1.1
Host: toko.contoh.id

v1 mengembalikan {"nama": "..."}, v2 mengembalikan struktur baru {"nama": "...", "varian": [...]}. Ini pola paling populer karena eksplisit dan mudah di-cache serta di-dokumentasikan terpisah.

Contoh 2: versioning lewat header

GET /api/produk/1 HTTP/1.1
Host: toko.contoh.id
Accept: application/vnd.toko.v2+json

URL tetap bersih, versi dinyatakan di header Accept custom. Pola ini elegan tapi lebih sulit dicoba manual dan di-cache (butuh Vary: Accept). GitHub API memakai pendekatan ini.

Aturan praktis kapan perlu versi baru: perubahan yang breaking (menghapus field, mengubah tipe data, mengubah arti field) wajib versi baru. Perubahan non-breaking (menambah field opsional) boleh masuk versi yang sama.

Kesalahan umum

Salah: menaikkan versi untuk setiap perubahan kecil. v47 dalam setahun membuat maintenance mimpi buruk. Yang benar: kumpulkan breaking changes, rilis versi baru berkala.

Salah: tidak pernah mempensiunkan versi lama. Mendukung v1 sampai v9 selamanya melipatgandakan beban. Yang benar: umumkan jadwal sunset (misalnya 6-12 bulan) dengan header Sunset dan Deprecation.

Salah: mengubah arti field tanpa versi baru. Field harga yang tadinya rupiah diam-diam jadi dolar. Yang benar: ini breaking change, wajib versi baru atau field baru.

Contoh header Sunset untuk pensiun versi

Saat mempensiunkan API v1, beri tahu klien dengan elegan:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: </api/v2/produk>; rel="successor-version"

{"data": "..."}

Header Deprecation: true menandai versi ini usang, Sunset memberi tanggal pasti kapan dimatikan, dan Link menunjuk penggantinya. Klien yang baik membaca header ini dan menampilkan peringatan ke developer mereka. Jauh lebih profesional daripada mematikan diam-diam.

Catatan teknis: Stripe memakai versioning berbasis tanggal (Stripe-Version: 2024-01-01), pola menarik untuk API yang berubah terus-menerus. Pelajari pola ini kalau API-mu dirilis ke publik dan berevolusi cepat.