Versi API untuk Integrasi Bisnis: Berubah Tanpa Merusak Mitra Anda
11 November 2026 · 7 menit baca · Tim Etzal Group
ERP sebuah distributor membuka antarmuka yang dipakai tiga marketplace, satu mitra logistik, dan aplikasi mobile perusahaan itu sendiri untuk membaca stok dan memasukkan pesanan. Pada suatu sore seorang developer merapikan jawaban stok, mengganti "qty" menjadi "quantity" dan mengubah format tanggal. Semuanya lolos uji internal. Malamnya pesanan dari satu marketplace berhenti masuk, sistem mitra logistik menampilkan semua barang kosong, dan versi lama aplikasi mobile macet saat dibuka. Tidak ada yang rusak di ERP. Yang rusak adalah sebuah kontrak. Versi API adalah disiplin mengubah antarmuka tanpa berbuat seperti itu.
API adalah sebuah janji
Ketika sistem lain bergantung pada antarmuka Anda, bentuknya adalah komitmen: alamat ini, masukan ini, keluaran ini, arti ini. Pihak seberang sudah menulis kode terhadapnya dan mungkin tidak akan melihat kode itu lagi selama setahun.
Anda mengendalikan sistem Anda. Anda tidak mengendalikan kapan sistem mereka berubah. Pemberian versi ada untuk menjembatani celah itu.
Apa yang merusak dan apa yang tidak
Biasanya aman, perubahan yang kompatibel ke belakang:
- Menambah endpoint baru.
- Menambah masukan opsional baru.
- Menambah kolom baru di jawaban.
- Menambah nilai baru di tempat pemakai sudah diberi tahu untuk mengharapkan nilai baru.
- Menjadikan masukan wajib menjadi opsional.
- Perbaikan kinerja.
Perubahan merusak:
- Menghapus atau mengganti nama kolom atau endpoint.
- Mengubah tipe: angka menjadi teks, nilai tunggal menjadi daftar.
- Mengubah format: tanggal, pemisah desimal, satuan, mata uang.
- Menjadikan masukan opsional wajib.
- Mengubah arti sebuah nilai. "Status 2" dulu berarti dikirim dan kini berarti dikemas.
- Mengubah perilaku bawaan: urutan, ukuran halaman, apa yang disertakan ketika tidak ada saringan.
- Memperketat validasi, sehingga masukan yang dulu diterima kini ditolak.
- Mengubah kode galat atau struktur jawaban galat.
- Mengubah autentikasi atau hak akses.
- Mengubah kapan sesuatu terjadi: operasi yang dulu seketika menjadi tertunda.
Dua peringatan. Menambah kolom hanya aman bila pemakai mengabaikan kolom yang tidak dikenalnya, jadi nyatakan di dokumentasi bahwa mereka harus begitu. Dan perubahan arti adalah yang paling berbahaya, karena tidak ada yang gagal secara terlihat. Datanya saja yang keliru.
Tiga cara memberi versi
1. Di alamat. /v1/orders dan /v2/orders.
Jelas, terlihat, dan mudah diarahkan. Pilihan paling lazim untuk integrasi bisnis, dan paling mudah dipahami mitra.
2. Di header. Alamatnya tetap, dan pemakai menyatakan versi yang diinginkan di header permintaan.
Alamat lebih bersih dan kendali lebih halus. Kurang terlihat, dan lebih mudah keliru bagi mitra.
3. Menurut tanggal. Tiap pemakai dikunci pada versi antarmuka sebagaimana adanya di tanggal tertentu, dan memilih sendiri untuk memakai perilaku yang lebih baru.
Cocok untuk penyedia dengan banyak pemakai dan perubahan kecil yang sering. Butuh lebih banyak perangkat di sisi penyedia.
Untuk perusahaan menengah yang berintegrasi dengan segelintir mitra, versi di alamat dengan angka bulat biasanya cukup. Yang lebih penting daripada caranya adalah punya satu cara dan mematuhinya.
Hindari keharusan membuat versi baru
Versi mayor baru itu mahal bagi semua pihak. Sebagian besar perubahan bisa dibuat tanpanya.
- Tambah, jangan ubah. Butuh format lain? Tambahkan kolom baru di samping yang lama. Pertahankan keduanya selama beberapa waktu.
- Perilaku baru di balik pilihan baru. Pemanggil lama yang tidak mengirimnya tetap mendapat perilaku lama.
- Rancang untuk tumbuh sejak awal. Kembalikan objek, bukan daftar atau nilai telanjang, agar kolom bisa ditambah nanti. Pakai kode teks untuk status, dan beri tahu pemakai bahwa yang baru bisa muncul.
- Ketat pada yang dijanjikan. Dokumentasikan hanya yang memang berniat Anda pertahankan. Apa pun yang tidak terdokumentasi dan telanjur diandalkan pemakai tetap menjadi janji.
- Jangan membuka basis data Anda. Antarmuka yang mencerminkan tabel internal rusak tiap kali tabelnya berubah. Rancang antarmuka di sekitar kebutuhan mitra, dan terjemahkan di dalam.
Antarmuka yang dirancang baik bisa berjalan bertahun-tahun di versi 1.
Kapan versi baru itu tepat
- Rancangan yang ada keliru dengan cara yang tidak bisa diperbaiki lewat penambahan.
- Masalah keamanan menuntut perilaku yang diubah.
- Sebuah aturan bisnis berubah secara mendasar.
- Tumpukan penambahan membuat antarmukanya membingungkan.
Bila begitu, buat versi barunya sepadan dengan migrasinya: perbaiki beberapa hal sekaligus, dan jangan merilis versi mayor baru tiap beberapa bulan.
Menghentikan versi lama
Penghentian adalah proses yang bertanggal.
- Umumkan. Saat versi baru dirilis, terbitkan tanggal penghentian yang lama. Beri mitra enam sampai dua belas bulan, atau lebih bila siklus rilis mereka lambat.
- Dokumentasikan migrasinya. Panduan yang mendaftar tiap perbedaan, dengan contoh sebelum dan sesudah.
- Beri tanda di jawaban. Tandai versi lama sebagai akan dihentikan di header jawaban, beserta tanggalnya.
- Ukur pemakaian. Catat pemakai mana memanggil versi mana. Anda tidak bisa menghentikan yang masih dipakai tanpa tahu siapa yang akan Anda rusak.
- Hubungi yang belum pindah. Langsung, menurut nama, jauh sebelum tanggalnya. Pengumuman tidak dibaca.
- Gladi akhirnya. Menjelang penghentian, matikan versi lama selama sejam pada waktu yang diumumkan. Siapa pun yang melewatkan semua pemberitahuan akan tahu selagi masih ada waktu.
- Hentikan. Kembalikan galat yang jelas dan menyebut versi barunya.
Menghentikan versi yang tidak dipakai siapa pun itu mudah. Pekerjaannya adalah mengetahui bahwa memang tidak ada yang memakainya.
Kenali pemakai Anda
- Beri tiap pemakai kredensialnya sendiri. Kunci bersama membuat mustahil mengetahui siapa yang memanggil.
- Simpan register: pemakai, orang kontak, endpoint dan versi yang dipakai, kapan terakhir memanggil.
- Jaga kontaknya tetap mutakhir. Developer yang membangun integrasi dua tahun lalu mungkin sudah keluar.
Ketika sebuah perubahan direncanakan, register ini adalah daftar orang yang harus diberi tahu.
Uji kontraknya
- Uji kontrak. Uji otomatis yang memeriksa antarmuka masih mengembalikan apa yang dijanjikan spesifikasinya. Dijalankan di tiap perubahan.
- Spesifikasi sebagai sumber kebenaran. Uraian antarmuka yang bisa dibaca mesin, yang darinya dokumentasi dan uji dihasilkan.
- Pemeriksaan kompatibilitas. Alat yang membandingkan spesifikasi baru dengan yang lama dan menandai perubahan merusak sebelum rilis.
- Sandbox untuk mitra. Lingkungan uji tempat mitra bisa mencoba versi baru dengan data yang aman.
Developer di cerita pembuka akan terhenti oleh satu uji kontrak yang menegaskan bahwa jawaban stok memuat "qty".
Aplikasi mobile adalah pemakai yang tidak bisa Anda perbarui
Aplikasi mobile Anda sendiri adalah kasus khusus. Pengguna memperbarui semaunya, dan sebagian tidak pernah. Versi lama terus memanggil antarmuka Anda selama berbulan-bulan atau bertahun-tahun.
- Dukung versi aplikasi lama selama jangka waktu yang ditetapkan.
- Tanam mekanisme "mohon perbarui" di aplikasi sejak rilis pertama, agar server bisa memberi tahu versi lama bahwa ia tidak lagi didukung.
- Pantau versi aplikasi mana yang masih aktif sebelum menghapus apa pun.
Ketentuan yang disepakati dengan mitra
Untuk integrasi antarperusahaan, tuangkan harapannya secara tertulis.
- Masa pemberitahuan untuk perubahan merusak.
- Masa dukungan minimum untuk tiap versi.
- Cara perubahan diumumkan, dan kepada siapa.
- Ketersediaan lingkungan uji.
- Siapa yang menanggung biaya migrasi.
- Batas laju dan pemakaian wajar.
- Kontak dukungan di kedua pihak.
Hal yang sama berlaku ketika Anda yang menjadi pemakai. Tanyakan mitra dan vendor Anda cara mereka memberi versi dan berapa lama pemberitahuannya.
Kesalahan yang umum
- Tanpa versi sama sekali, sampai kerusakan pertama.
- Perubahan "kecil" pada kolom yang ada.
- Mengubah arti tanpa mengubah struktur.
- Kredensial bersama, sehingga tidak ada yang tahu siapa memakai apa.
- Mengumumkan penghentian tanpa mengukur pemakaian.
- Terlalu banyak versi hidup sekaligus. Dua masih terkelola. Lima menjadi beban.
- Membuka struktur internal secara langsung.
- Melupakan versi aplikasi mobile yang lama.
- Dokumentasi yang menggambarkan maksud developer, bukan apa yang dikerjakan antarmukanya.
Kami merancang antarmuka integrasi lengkap dengan kebijakan versi dan uji kontrak sebagai bagian dari Enterprise Software. Bila mitra bergantung pada antarmuka Anda dan tiap rilis terasa berisiko, hubungi kami.
Ringkasan
Perlakukan antarmuka yang diandalkan pihak lain sebagai kontrak. Ketahui perubahan mana yang merusak pemakai, termasuk perubahan arti yang senyap. Beri versi di alamat kecuali ada alasan lain, dan utamakan menambah daripada mengubah agar versi baru jarang dibutuhkan. Hentikan versi lama menurut jadwal yang diumumkan, dengan panduan migrasi, pengukuran pemakaian, kontak langsung, dan gladi. Beri tiap pemakai kredensialnya sendiri, uji kontraknya secara otomatis, rencanakan untuk versi aplikasi mobile lama, dan sepakati masa pemberitahuan dengan mitra secara tertulis.
Pertanyaan yang sering diajukan
Apa itu perubahan merusak (breaking change) pada API?
Perubahan apa pun yang bisa membuat integrasi yang ada gagal atau berperilaku lain tanpa pemiliknya mengubah apa pun: menghapus atau mengganti nama kolom, mengubah tipe atau format data, menjadikan masukan opsional wajib, mengubah arti sebuah nilai, mengubah kode galat, atau memperketat validasi. Menambah kolom opsional baru dan endpoint baru umumnya aman.
Berapa lama versi API lama perlu didukung?
Cukup lama agar tiap pemakai bisa berpindah dengan nyaman. Untuk integrasi antarusaha, enam sampai dua belas bulan setelah penggantinya tersedia adalah yang lazim, dan lebih lama bila siklus rilis mitra lambat. Umumkan tanggal penghentian saat versi baru dirilis, dan pantau siapa yang masih memakai yang lama.
Apakah API internal butuh versi?
Bila pemakai dan penyedianya dipasang bersama oleh tim yang sama, tidak terlalu. Begitu tim lain, aplikasi mobile yang diperbarui pengguna semaunya, atau mitra luar bergantung pada antarmuka itu, perlakukan sebagai kontrak. Aplikasi mobile khususnya membuat versi lama tetap dipakai berbulan-bulan.
Layanan terkait
Jasa Pembuatan Website
Website cepat dan SEO-ready yang mengubah pengunjung jadi pelanggan.
