Versi REST API: URL, header, atau query, mana yang cocok

Versi REST API adalah cara sebuah API memberi tahu pemanggil kontrak mana yang dipakai sebuah request, sehingga server bisa mengubah kontraknya tanpa merusak pemanggil yang belum pindah. Ada tiga tempat untuk menaruh versinya: path URL (/v2/orders), header request (Accept: application/vnd.acme.v2+json atau header kustom Api-Version: 2026-10-01), atau parameter query (/orders?version=2). Path paling umum karena terlihat di mana-mana, header paling bersih untuk URL, dan query string adalah pilihan yang paling sering disesali tim. Mana yang cocok tergantung siapa pemanggil Anda dan bagaimana Anda berencana memberi tahu mereka tentang perubahan.

Apa itu v1 dan v2 di REST API?

v1 dan v2 adalah label untuk dua versi kontrak API: resource yang sama, dijangkau lewat path yang berbeda, di mana v2 boleh mengganti nama field, mengubah tipe, menghapus endpoint, atau mengubah bentuk error yang diandalkan pemanggil v1. Request ke /v1/orders terus mendapat bentuk lama selama v1 masih didukung; request ke /v2/orders mendapat bentuk baru. Nomor itu adalah janji tentang kompatibilitas, dan janji itulah yang membuatnya berguna. Menaikkannya di setiap rilis mengubah label itu menjadi kebisingan.

Kebanyakan API hanya butuh versi mayor baru untuk perubahan yang merusak pemanggil yang ada. Menambah field, endpoint baru, atau parameter opsional baru bisa dirilis di bawah versi saat ini, karena klien yang ditulis dengan baik mengabaikan apa yang tidak dikenalnya. Kapan memversikan API, dan apa yang dilakukan sebagai gantinya membahas keputusannya; artikel ini membahas di mana versi diletakkan dalam versi REST API begitu Anda memutuskan untuk menaikkannya.

Haruskah versi REST API ditaruh di URL atau di header?

Taruh di URL jika pemanggil Anda termasuk orang yang mengetik request di browser, menyalin contoh dari dokumentasi, atau membaca log; taruh di header jika Anda ingin satu URL stabil per resource dan semua pemanggil Anda adalah SDK atau kode yang Anda kendalikan. Path URL eksplisit dengan cara yang tidak dimiliki yang lain: tiket dukungan yang memuat baris request-nya sudah memberi tahu Anda versinya. Header harus dikirim di setiap request, tidak terlihat di tautan, dan mudah hilang di proxy, itulah sebabnya API berversi header selalu mendefinisikan default untuk request yang tidak mengirimnya.

Pendekatan header punya satu keunggulan nyata selain URL yang rapi: ia memisahkan identitas resource dari representasinya, yang memang cara HTTP dirancang. RFC 9110 menjelaskan negosiasi konten lewat Accept, dan media type seperti application/vnd.github.v3+json adalah versi yang dinyatakan dengan cara itu. Dalam praktiknya, kemurnian desain kalah penting dibanding apakah pemanggil Anda ingat mengirim header-nya.

Bagaimana cara kerja versi berbasis tanggal?

Alih-alih v1 dan v2, versinya berupa tanggal, dan setiap breaking change mendapat tanggal baru. Pemanggil mengunci tanggal saat mereka berintegrasi, biasanya sekali di tingkat akun, dan mempertahankan perilaku itu sampai mereka memilih untuk pindah. Header Stripe-Version milik Stripe dan X-GitHub-Api-Version milik GitHub keduanya bekerja seperti ini.

Kompromi-nya ada di implementasi. Setiap breaking change menjadi lapisan transformasi kecil yang mengonversi antara tanggal yang dikunci dan bentuk saat ini, dan server menumpuknya: request yang dikunci dua tahun lalu melewati setiap perubahan sejak saat itu. Itu lebih berat dibangun daripada salinan kedua dari handler-nya, dan cocok untuk API yang jarang berubah. Tim yang merilis satu breaking change per bulan berakhir dengan puluhan transformasi. Versi API Stripe melihat model ini dari sisi pemanggil, termasuk apa yang harus dimuat changelog-nya.

Mengapa versi di query string tidak dianjurkan?

Karena ia mencampur kontrak dengan filter. /orders?status=open&api-version=2 membuat versi terlihat seperti penyaring opsional, bukan hal yang menentukan bentuk setiap field dalam respons. Ia juga yang paling mudah terbuang tanpa sengaja, karena query string dibangun ulang oleh library klien, dibuang oleh sebagian proxy, dan diedit tangan oleh orang. Panduan desain REST API milik Microsoft mendokumentasikan bentuk parameter query yang dipakai Azure, dan ekosistem SDK hasil generator di sekitarnya yang membuatnya bisa bekerja; tanpa perangkat itu, pemanggil yang lupa parameternya diam-diam mendapat versi default.

Apa yang terjadi pada versi lama?

Ia tetap berjalan, dengan tanggal kapan ia berhenti. Tujuan versi adalah membiarkan pemanggil pindah sesuai jadwal mereka sendiri, dan itu hanya benar jika versi lama tetap tersedia cukup lama bagi mereka untuk melakukannya dan mereka diberi tahu kapan berakhirnya. Panduan versi API milik Google menjelaskan siklus hidup yang dipakai untuk API-nya sendiri: versi stabil didukung sampai tanggal deprecation yang dipublikasikan, dengan penggantinya tersedia selama seluruh jendela deprecation.

Pengumuman adalah bagian yang paling sering kurang dibangun tim. Path atau header baru hanya berguna bagi pemanggil yang tahu ia ada, tahu apa yang berubah, dan tahu kapan v1 hilang. Itu tiga fakta, dan masing-masing butuh rumah: entri bertanggal di changelog API dengan perbedaan di tingkat field, pemberitahuan deprecation yang menyebut tanggal akhir, dan panduan migrasi yang memandu setiap perubahan bagi pemanggil yang masih di versi lama. Menghentikan versi API membahas langkah terakhirnya, termasuk header Sunset yang membuat klien bisa menemukan tanggalnya di setiap respons.

Bisakah versi REST API dihindari sama sekali?

Bisa, selama setiap perubahan bersifat aditif. Tambahkan field, jangan pernah hapus atau ganti namanya; tambahkan endpoint, jangan pernah ubah apa yang dikembalikan endpoint yang ada; terima parameter opsional baru, jangan pernah ubah makna parameter lama. Banyak API internal berjalan bertahun-tahun hanya dengan aturan ini, dan itulah aturan yang diikuti skema GraphQL dari rancangannya. Biayanya adalah kontrak yang hanya bisa tumbuh, dengan field deprecated yang harus tetap ada karena seseorang, di suatu tempat, masih membacanya.

Ketika perubahan aditif mustahil, versi adalah alatnya. Pilihan antara path, header, dan tanggal menentukan apa yang dilihat pemanggil dan bagaimana perubahan diumumkan; yang tetap sama adalah perubahan itu harus dituliskan di tempat yang akan dibaca pemanggil. Untuk API dengan pemanggil eksternal, tempat itu adalah changelog, dan artikel breaking change membahas apa yang terhitung sebagai salah satunya.

FAQ

Apa cara terbaik memversikan REST API? Versi mayor di path URL paling luas dipahami dan paling sulit salah, yang menjadikannya default untuk API publik. Versi di header menjaga URL tetap stabil dan cocok untuk API yang digerakkan SDK; header berbasis tanggal cocok untuk API yang jarang berubah dan ingin pemanggil mengunci perilaku.

Apa itu v1 di URL API? Itu versi mayor pertama dari kontrak API. Request ke /v1/... dijanjikan bentuk yang didokumentasikan untuk versi 1, bahkan setelah /v2/ ada dengan field atau perilaku yang berbeda.

Apakah saya butuh versi API baru untuk setiap perubahan? Tidak. Perubahan aditif seperti field, endpoint, dan parameter opsional baru bisa dirilis di bawah versi yang ada. Hanya perubahan yang merusak pemanggil yang ada yang butuh versi baru.

Berapa lama versi API lama harus didukung? Cukup lama bagi pemanggil untuk bermigrasi, yang untuk API publik biasanya enam sampai dua belas bulan setelah penggantinya tersedia, dengan tanggalnya dipublikasikan saat pengumuman dan diulang di pemberitahuan deprecation.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Dokumentasi developer, Contoh changelog