Strategi Versioning API yang Nggak Bikin Klien Panik

Daftar Isi

Kenapa API Versioning Itu Penting?
Tiga Pendekatan Versioning yang Umum
URL Path Versioning: Paling Mudah Dimulai
Header Versioning: Lebih Bersih, Tapi Lebih Kompleks
Semantic Versioning dan Strategi Deprecation
Tips Praktis Menjaga Backward Compatibility
Kesimpulan

Kenapa API Versioning Itu Penting?

Setiap API yang kamu buat hari ini hampir pasti perlu berubah di masa depan. Fitur bertambah, skema data berubah, nama field diganti, atau endpoint lama perlu dihapus karena sudah tidak relevan. Masalahnya, di sisi lain ada klien (bisa berupa mobile app, frontend web, atau integrasi pihak ketiga) yang bergantung pada struktur data yang kamu kirim sekarang.

Kalau kamu langsung mengubah respons API tanpa pemberitahuan, misalnya mengganti nama field user_name menjadi username, aplikasi klien yang belum diperbarui bisa langsung crash. Ini adalah breaking change yang paling ditakuti developer.

API Versioning adalah strategi untuk mengelola perubahan tersebut tanpa memutus layanan yang sudah berjalan. Tujuannya adalah memberikan waktu yang cukup kepada tim klien untuk menyesuaikan integrasi mereka sembari kamu tetap bisa melakukan evolusi pada API.

Tiga Pendekatan Versioning yang Umum

Ada beberapa pendekatan yang paling sering dipakai untuk memberi versi pada API:

URL Path Versioning — Versi dituliskan langsung di URL. Contoh: /api/v1/users, /api/v2/users.
Header Versioning — Versi dikirimkan melalui HTTP Header kustom. Contoh: Accept: application/vnd.api+json;version=2 atau header X-API-Version: 2.
Query Parameter Versioning — Versi ditambahkan sebagai parameter URL. Contoh: /api/users?version=2. Pendekatan ini paling jarang direkomendasikan karena merusak cache dan sulit dibaca.

Tidak ada pendekatan yang secara universal paling “terbaik”. Setiap pilihan punya trade-off yang perlu disesuaikan dengan kebutuhan tim.

URL Path Versioning: Paling Mudah Dimulai

URL Path Versioning adalah pilihan paling populer, terutama untuk API publik, karena alasannya mudah dipahami: kamu bisa langsung melihat versi API hanya dari URL-nya.

GET /api/v1/orders
GET /api/v2/orders

Kelebihan:

Intuitif dan mudah dibaca oleh developer.
Mudah diuji langsung di browser atau Postman tanpa konfigurasi header tambahan.
Tools dokumentasi seperti Swagger/OpenAPI bisa memisahkan spesifikasi per versi dengan mudah.

Kekurangan:

URL menjadi lebih panjang dan terasa redundan (/api/v1/..., /api/v2/...).
Menyebabkan duplikasi kode di backend jika tidak dikelola dengan baik.
Secara teoritis melanggar prinsip REST bahwa satu resource harus punya satu URL kanonik.

Header Versioning: Lebih Bersih, Tapi Lebih Kompleks

Dengan pendekatan ini, URL tetap bersih (/api/orders) dan versi dikirim lewat HTTP Header. GitHub API adalah contoh nyata yang memakai pendekatan ini dengan header Accept.

GET /api/orders
Accept: application/vnd.myapp.v2+json

Kelebihan:

URL tetap bersih dan semantik, sesuai prinsip REST.
Memungkinkan perubahan versi tanpa mengubah URL yang sudah tersebar di klien.

Kekurangan:

Lebih susah diuji secara cepat (butuh alat seperti Postman atau curl).
Logika routing di backend menjadi lebih kompleks karena harus mem-parse header.
Developer klien sering lupa menambahkan header, menyebabkan bug yang sulit didiagnosis.

Semantic Versioning dan Strategi Deprecation

Setelah memilih pendekatan versioning, langkah berikutnya yang sering dilupakan adalah menetapkan strategi deprecation yang jelas.

Prinsip Utama:

Jangan pernah menghapus sebuah versi API tanpa sunset period yang memadai, umumnya minimal 6-12 bulan untuk API publik.
Tambahkan header Deprecation atau Sunset di respons versi lama agar klien tahu kapan versi tersebut tidak akan dilayani lagi. Contoh: Deprecation: true, Sunset: Sat, 01 Jan 2028 00:00:00 GMT.
Kirimkan notifikasi aktif ke semua pengguna API yang teregistrasi melalui email atau developer dashboard.

Semantic Versioning untuk API: Meski SemVer (v1.2.3) lebih lazim di library/package, konsep mayor-minor-patch bisa diadaptasi: versi mayor naik saat ada breaking change, versi minor naik untuk fitur baru yang backward-compatible.

Tips Praktis Menjaga Backward Compatibility

Sebelum menaikkan versi API, ada beberapa teknik yang bisa memperpanjang umur versi yang sudah ada:

Jangan hapus field, tambahkan saja. Kalau kamu ingin mengganti nama field, pertahankan field lama di respons dan tambahkan field baru. Dokumentasikan field lama sebagai deprecated.
Buat semua field baru bersifat opsional. Jangan mewajibkan klien mengirim field baru yang tidak ada di versi sebelumnya di request body. Gunakan nilai default jika field tidak dikirim.
Gunakan Expand Pattern. Alih-alih mengubah struktur, tambahkan objek/field opsional yang bisa di-expand jika klien memintanya. Contoh seperti pada Stripe API: /charges?expand[]=customer.
Kontrak API adalah kontrak sosial. Perlakukan setiap perubahan API seperti perubahan kontrak bisnis dengan klien kamu. Komunikasikan jauh-jauh hari, sediakan changelog, dan beri waktu adaptasi.

Kesimpulan

API versioning adalah keseimbangan antara kemampuan evolusi produk dan keandalan ekosistem klien. Pilih pendekatan yang paling jelas bagi tim dan komunitas developer kamu, tetapkan sunset policy yang manusiawi, dan selalu prioritaskan komunikasi perubahan sebelum mengeksekusinya.

Satu aturan emas: jangan pernah melakukan breaking change tanpa memberi jalan keluar yang jelas kepada klien kamu.