API Versioning: Saat Integrasi Vendor Berubah

Integrasi bisa berhenti meski tim Anda tidak mengubah kode. API vendor dapat mengganti format data, menghentikan versi, atau mencabut akses. API versioning, yaitu penomoran versi antarmuka, membantu menjadwalkan perubahan. Kalau vendor tidak menyediakannya, tim perlu menguji kontrak data, membatasi penyesuaian di satu tempat, dan menyepakati kanal pemberitahuan.

Contohnya terjadi pada 12 Januari 2023: Tweetbot, Twitterrific, Echofon, Fenix, Twitpane, Feather, dan Talon berhenti bekerja bersamaan. Pengguna tidak dapat masuk dan aplikasi berstatus ditangguhkan di portal pengembang Twitter, tanpa pemberitahuan sebelumnya. Seminggu kemudian, perubahan perjanjian pengembang menetapkan larangan tersebut secara permanen.

Integrasi tim-tim itu berhenti karena perubahan kebijakan vendor, tanpa pemberitahuan penghentian dukungan atau versi lama yang dapat digunakan kembali. Artikel ini membahas perlindungan ketika API pihak lain berubah atau tidak menyediakan pengelolaan versi.

Kebijakan vendor berbeda-beda: ada yang menyediakan versi dan masa transisi, ada yang mengubah layanan tanpa peringatan. Rancang integrasi untuk menghadapi kemungkinan kedua, karena tim Anda tidak mengendalikan rencana pengembangan vendor.

Bentuk pengelolaan versi yang dapat diandalkan

Versi pada jalur URL atau parameter kueri (/v2/orders) paling umum dan paling mudah dipahami. Versi melalui header khusus menjaga URL tetap, tetapi perlu dipastikan selalu dikirim oleh pustaka klien. Versi melalui jenis media (Accept: application/vnd.vendor.v2+json) membedakan format respons melalui header Accept, meskipun tidak banyak vendor memakainya.

Stripe menyediakan versi API bertanggal, misalnya 2024-09-30.acacia. Permintaan HTTP langsung memakai versi bawaan akun jika tidak ada penggantian melalui header Stripe-Version; SDK modern dapat menetapkan versi sesuai rilis SDK. Periksa versi yang benar-benar dipakai oleh aplikasi dan webhook, lalu uji peningkatannya di lingkungan praproduksi. (docs, upgrade guide)

GitHub merekomendasikan header X-GitHub-Api-Version di setiap permintaan. Jika header tidak dikirim, GitHub memakai versi bawaan yang dapat berubah ketika versi lama dihentikan. Versi sebelumnya didukung setidaknya 24 bulan setelah versi baru dirilis. Periksa header peringatan Deprecation/Sunset; permintaan ke versi yang sudah dihentikan mengembalikan 410 Gone. (docs)

Shopify merilis versi bertanggal tiap kuartal, dengan jaminan 12 bulan dukungan dan 9 bulan overlap. Permintaan untuk versi yang sudah dihentikan dialihkan ke versi yang masih didukung. Sebagai contoh, jika 2026-10 sudah dihentikan dan 2027-01 saat itu merupakan versi tertua yang masih didukung, permintaan 2026-10 dilayani sebagai 2027-01. (docs)

Vendor yang Anda temui, seperti agregator pembayaran regional, penyedia SDK perangkat keras, atau pengelola kanal penjualan, mungkin hanya menyediakan satu versi API. Tanyakan kebijakan perubahannya sebelum mengandalkan pola versi seperti pada contoh di atas.

Pola 1: baca data yang diperlukan secara toleran

Pola Tolerant Reader dari Martin Fowler menerapkan prinsip Postel pada pembacaan data. Ambil kolom data yang dibutuhkan dari respons dan abaikan tambahan yang aman. Nilai bawaan hanya sesuai untuk kolom opsional. Nominal pembayaran, identitas pesanan, status, dan tanda tangan yang wajib tetap harus divalidasi; jika hilang atau salah, tahan proses dan beri peringatan.

Contoh Fowler memakai XPath: kueri //order tidak mengunci pencarian pada jalur absolut yang kaku. Jika vendor menyisipkan elemen pembungkus, integrasinya tetap berjalan. Pada JSON, baca response.customer.email langsung. Hindari validasi seluruh objek dengan bentuk yang wajib persis sama, dan jangan mengandalkan urutan kolom data.

Fowler menautkan tulisan Ian Cartwright yang menandai satu hal penting: validasi skema yang ketat dapat memberi "rasa aman yang palsu." Skema yang mensyaratkan setiap kolom data secara persis dapat menolak perubahan yang aman maupun yang merusak integrasi. Pusatkan pembacaan respons di satu tempat, biasanya objek pemindah data (data transfer object, DTO). Dengan begitu, bentuk respons asli vendor hanya perlu dipahami oleh satu bagian kode.

Pola 2: uji kontrak data sebagai peringatan dini

Pola Consumer-Driven Contracts dari Fowler dibangun untuk tim internal. Setiap pengguna API menulis pengujian atas kolom data dan perilaku yang dibutuhkannya. Penyedia menjalankan pengujian tersebut pada hasil pengembangannya untuk mendeteksi perubahan yang merusak integrasi sebelum rilis.

Anda mungkin tidak dapat memasukkan pengujian ke proses rilis vendor. Namun, uji kontrak data (contract test) dapat dijalankan secara terjadwal pada lingkungan uji mereka. Periksa kolom data, tipe data, dan kode status yang dibutuhkan integrasi setiap malam. Hasilnya menjadi peringatan dini jika bentuk respons berubah; pengujian ini tidak dapat mencegah vendor merilis perubahan.

Pola 3: pisahkan model data vendor dari model aplikasi

Gunakan lapisan penerjemah (anti-corruption layer) sebagai satu pintu masuk data vendor ke model aplikasi Anda.

Tanpa batas ini, vendor yang mengganti nama customer_email menjadi contact_email mengharuskan pencarian perubahan di setiap layanan yang memakai data pesanan. Dengan batas ini, penggantian nama itu dapat ditangani dalam satu berkas pada lapisan penerjemah. Semua yang di hilirnya tidak pernah tahu nama kolom datanya berubah — logika pembacaan data tetap berada di lapisan tersebut.

Pola 4: tetapkan versi dan pantau perubahan

Jika vendor mendukungnya, tetapkan versi tertentu (pinning) agar pembaruan dapat Anda jadwalkan. Penomoran versi bertanggal saja belum cukup; periksa juga masa dukungan dan kebijakan transisinya.

Jika versi tidak dapat ditetapkan, pemantauan perubahan menjadi semakin penting. Jalankan uji kontrak data dari pola 2 terhadap produksi juga, bukan hanya sandbox. Keduanya bisa saling menyimpang, atau sandbox-nya tidak pernah disentuh sama sekali. Perbandingan bentuk respons dapat menangkap penyimpangan pada pemeriksaan berikutnya. Cara ini tidak mendeteksi semua perubahan perilaku atau kebijakan akses.

Tuliskan kewajiban notifikasi perubahan di kontrak

Pertahanan teknis baru separuh urusan. Separuh lainnya bersifat kontraktual, dan tetap layak dilakukan meski sebagian besar vendor tidak akan mencapai disiplin setara Stripe atau GitHub.

Microsoft REST API Guidelines mendefinisikan perubahan yang merusak kompatibilitas (breaking change) sebagai perubahan yang memengaruhi kontrak API atau kesesuaian dengan versi sebelumnya. Setiap tim layanan perlu menyusun daftar konkretnya. Dalam contoh pedoman tersebut, Azure menganggap kolom baru pada respons JSON sebagai perubahan yang merusak kompatibilitas, sedangkan Office 365 tidak. Minta vendor memberikan definisi yang spesifik untuk API mereka.

Kebijakan perubahan API LinkedIn memberikan contoh lebih rinci. Penghapusan kolom, penambahan parameter wajib tanpa nilai bawaan, atau peralihan DELETE dari penandaan hapus (soft delete) ke penghapusan permanen (hard delete) memerlukan pemberitahuan surel sebelumnya. Perubahan yang tetap kompatibel, seperti kolom opsional baru, dapat dirilis tanpa pemberitahuan.

LinkedIn juga berhak melewati notifikasi untuk perbaikan bug kritis, hukum, keamanan, atau privasi. Baca pengecualian ini baik-baik — justru itulah jenis perubahan yang biasanya merusak integrasi.

Minta tiga hal saat negosiasi: definisi tertulis soal "merusak kompatibilitas" yang spesifik untuk API mereka, periode notifikasi minimum, dan kanal pemberitahuan yang benar-benar dipantau. Kanal itu berarti email atau webhook, bukan halaman catatan perubahan yang tidak dipantau. Kesediaan vendor bergantung pada kebijakan serta posisi negosiasi kedua pihak. Itulah sebabnya empat pola teknis di atas tetap perlu dibangun, terlepas dari isi kontrak.

Yang harus diminta, dan yang harus tetap dibangun

Sebelum menandatangani kontrak, sepakati definisi tertulis untuk perubahan yang merusak kompatibilitas, masa pemberitahuan minimum, serta kanal pemberitahuan yang dipantau. Tetapkan juga versi tertentu jika vendor mendukungnya.

Bangun terlepas dari apa yang mereka janjikan: pembaca toleran pada batas masuk respons vendor, dan uji kontrak data terjadwal terhadap sandbox dan produksi. Tambahkan lapisan penerjemah sebagai satu titik penyesuaian, dan pemantauan dengan frekuensi yang sesuai kebutuhan operasional. Pengujian terjadwal baru dapat menangkap perubahan pada pemeriksaan berikutnya. Kesepakatan vendor membantu mengurangi risiko. Pengujian dan pemantauan tetap diperlukan untuk mendeteksi perubahan yang tidak diumumkan.

Kalau integrasinya mencakup banyak jenis perangkat keras atau protokol, bukan hanya satu REST API, gagasan lapisan penerjemah yang sama muncul lagi di normalisasi perangkat IoT multi-protokol. Masalah berbeda, solusi yang sama.