API Versioning: Cara Update API Tanpa Bikin Aplikasi Mobile Versi Lama Langsung Error Semua

Bayangin Budi Merapikan Bentuk Response API-nya...

Bayangin Budi merasa response endpoint /api/profile miliknya kurang rapi: { nama: "Budi", no_hp: "0812..." }. Dia "membenahinya" menjadi bentuk lebih modern: { name: "Budi", phone: { number: "0812...", verified: true } }, lalu langsung men-deploy perubahan itu ke server production.

Fitur baru di aplikasi mobile versi terbaru berjalan mulus membaca bentuk data baru itu. Tapi keesokan harinya, customer service Budi kebanjiran keluhan: ribuan pengguna yang belum meng-update aplikasi mobile mereka (dan mungkin tidak akan pernah update) tiba-tiba melihat layar kosong, karena kode aplikasi lama mereka mencoba membaca response.nama dan response.no_hp yang sekarang sudah tidak ada lagi bentuknya.

Masalahnya: Satu URL API, Tapi Dipakai oleh Banyak Versi Aplikasi Client Sekaligus

Berbeda dengan website yang selalu memuat kode terbaru setiap kali dibuka, aplikasi mobile yang sudah ter-install di HP pengguna tidak otomatis ter-update. Sebuah API yang sama harus tetap bisa melayani versi aplikasi lama yang masih terpasang di jutaan HP, sekaligus melayani versi terbaru — padahal keduanya mengharapkan bentuk response yang berbeda.

Nah, Di Sinilah 'API Versioning' Masuk!

Solusinya: jangan pernah mengubah bentuk endpoint yang sudah dipakai secara live. Sebaliknya, buat versi baru di samping versi lama, dan biarkan keduanya hidup berdampingan untuk sementara waktu.

• URL Path Versioning (paling umum): /api/v1/profile tetap dipertahankan persis seperti sebelumnya untuk aplikasi lama, sementara endpoint baru dibuat terpisah di /api/v2/profile dengan bentuk response yang sudah dirapikan. Aplikasi lama tidak pernah tahu ada v2, dan tidak akan pernah rusak karenanya.
• Header Versioning: URL-nya tetap sama (/api/profile), tapi client mengirim header seperti Accept-Version: 2, dan server membaca header itu untuk memutuskan bentuk response mana yang harus dikirim balik.

app.use("/api/v1/profile", oldProfileController);
app.use("/api/v2/profile", newProfileController);

Setelah cukup lama (misalnya beberapa bulan) dan data analitik menunjukkan hampir tidak ada lagi trafik yang memakai /v1, barulah endpoint versi lama itu resmi dipensiunkan (deprecated) dan akhirnya dihapus.

Intinya: Kalau API-mu dikonsumsi oleh sesuatu yang tidak bisa kamu paksa update secara instan (aplikasi mobile, integrasi partner pihak ketiga), jangan pernah mengubah kontrak endpoint yang sudah berjalan. Tambahkan versi baru, jangan menimpa versi lama.