Perubahan Kecil di API Bisa Menjadi Gangguan Besar bagi Sistem Lama
Sebuah tim mengubah nama kolom “phone_number” menjadi “mobile_number” karena dianggap lebih sesuai. Di sisi pengembang, perubahan itu terlihat kecil. Namun beberapa jam kemudian, aplikasi lama gagal memproses pendaftaran pengguna. Mitra integrasi juga mulai mengirim keluhan karena sistem mereka tidak lagi bisa membaca jawaban dari layanan.
Inilah masalah klasik dalam perubahan API. Bagi tim pembuat layanan, perubahan tampak sebagai perbaikan. Bagi pengguna API, perubahan itu bisa berarti kerusakan mendadak.
Karena itu, versi API bukan sekadar penanda teknis. Ia adalah cara menjaga perjanjian antara sistem baru dan sistem lama agar tetap bisa berjalan berdampingan.
API Adalah Kontrak, Bukan Sekadar Jalur Data
Dalam integrasi sistem, API berfungsi seperti kontrak. Ia menjelaskan bentuk permintaan, bentuk jawaban, kode kesalahan, aturan autentikasi, dan perilaku layanan.
Masalah muncul ketika kontrak itu berubah tanpa pemberitahuan yang jelas. Contohnya, tim menghapus kolom yang sebelumnya digunakan aplikasi lama. Atau tim mengubah jenis data dari angka menjadi teks. Bisa juga tim mengganti nama “status” menjadi “order_status”, mengubah format tanggal, atau mengganti kode kesalahan tanpa penjelasan yang terdokumentasi.
Perubahan seperti ini disebut perubahan yang merusak kompatibilitas. Dampaknya tidak selalu langsung terlihat di sistem utama, tetapi bisa muncul di aplikasi mitra, aplikasi bergerak versi lama, atau proses otomatis yang jarang dipantau.
Kapan Versi Baru Perlu Dibuat?
Tidak semua perubahan membutuhkan versi baru. Menambahkan kolom baru dalam jawaban biasanya aman jika pengguna API tidak diwajibkan membacanya. Namun menghapus atau mengubah makna kolom lama sebaiknya diperlakukan sebagai perubahan besar.
Versi baru perlu dipertimbangkan ketika perubahan:
- Menghapus bidang yang sudah ada.
- Mengubah nama atau jenis data.
- Mengubah aturan wajib dan tidak wajib.
- Mengubah format jawaban.
- Mengubah perilaku bisnis yang sudah digunakan pihak lain.
Misalnya, layanan pesanan sebelumnya mengembalikan nomor pesanan dan status pesanan dalam satu bidang sederhana bernama “status”. Lalu tim ingin membuat status lebih rinci dengan memisahkan “payment_status” dan “fulfillment_status”.
Secara desain, bentuk baru memang lebih jelas. Namun jika aplikasi lama masih membaca “status”, perubahan langsung akan membuat aplikasi itu rusak. Solusinya bukan memaksa semua pengguna berubah saat itu juga, melainkan menyediakan versi baru sambil mempertahankan versi lama untuk masa tertentu.
Pilihan Cara Membuat Versi API
Ada beberapa cara umum untuk menandai versi API. Setiap pilihan punya konsekuensi.
Cara pertama adalah melalui alamat, misalnya “/v1/orders” dan “/v2/orders”. Ini mudah dipahami dan mudah diuji. Banyak tim memilih pendekatan ini karena jelas terlihat di dokumentasi dan catatan akses.
Cara kedua adalah melalui header, misalnya dengan mengirim informasi versi di bagian permintaan. Pendekatan ini membuat alamat tetap bersih, tetapi membutuhkan kedisiplinan lebih pada pengguna API.
Cara ketiga adalah menggunakan versi berdasarkan tanggal, misalnya versi “2026-04-01”. Pola ini berguna jika perubahan cukup sering dan tim ingin menunjukkan kapan kontrak mulai berlaku.
Tidak ada satu cara yang selalu paling benar. Untuk sistem dengan banyak mitra eksternal, versi pada alamat sering lebih mudah dipahami. Untuk sistem internal dengan pengendalian ketat, versi melalui header bisa lebih rapi.
Yang penting, cara tersebut konsisten dan tidak berubah-ubah di tengah jalan.
Jangan Hanya Membuat Versi, Rancang Masa Peralihannya
Kesalahan yang sering terjadi adalah tim membuat versi baru, lalu menganggap tugas selesai. Padahal pekerjaan terpenting justru ada pada masa peralihan.
Versi lama perlu punya jadwal penghentian yang jelas. Misalnya, versi pertama masih didukung selama 12 bulan sejak versi kedua tersedia. Selama masa itu, tim perlu memberi peringatan di dokumentasi, catatan perubahan, dan jawaban API bila memungkinkan.
Dengan cara ini, pengguna API tidak hanya tahu bahwa versi lama akan dihentikan, tetapi juga punya tenggat waktu yang konkret.
Untuk mitra besar, pemberitahuan sebaiknya tidak hanya lewat dokumentasi. Tim integrasi perlu menghubungi mereka secara langsung, terutama jika perubahan menyentuh proses bisnis penting seperti pembayaran, pengiriman, atau pelaporan.
Dokumentasi Harus Menjelaskan Perbedaan, Bukan Hanya Bentuk Baru
Dokumentasi versi baru sering hanya berisi daftar endpoint. Itu belum cukup. Pengguna API perlu tahu apa yang berubah dari versi sebelumnya.
Dokumentasi yang baik sebaiknya mencantumkan bidang yang ditambah, bidang yang dihapus, perubahan nama bidang, perubahan format data, contoh permintaan dan jawaban lama dibandingkan yang baru, serta panduan pemindahan dari versi lama ke versi baru.
Misalnya, jangan hanya menulis “gunakan payment_status”. Jelaskan bahwa “status” pada versi lama dipisah menjadi “payment_status” dan “fulfillment_status” pada versi baru. Penjelasan seperti ini mengurangi salah tafsir dan mempercepat pekerjaan tim integrasi.
Versi yang Rapi Membuat Perubahan Lebih Aman
Sistem teknologi pasti berubah. Produk bertambah, aturan bisnis bergeser, dan kebutuhan integrasi makin rumit. Masalahnya bukan pada perubahan itu sendiri, melainkan pada perubahan yang membuat sistem lama langsung jatuh.
Versi API membantu tim bergerak maju tanpa meninggalkan pengguna lama secara mendadak. Ia memberi ruang bagi aplikasi lama untuk tetap berjalan, sementara sistem baru bisa diperbaiki dengan struktur yang lebih baik.
Desain versi yang baik tidak hanya memikirkan pengembang yang membuat API, tetapi juga orang dan sistem yang bergantung padanya. Di sanalah arsitektur yang matang terlihat: bukan dari seberapa cepat perubahan dibuat, tetapi dari seberapa kecil gangguan yang ditimbulkan saat perubahan itu sampai ke dunia nyata.
Tidak ada komentar:
Posting Komentar