Pembaruan spesifikasi API secara manual kini bisa diotomatisasi dengan bantuan agent kecerdasan buatan melalui CLI Apidog. Proses yang tadinya memakan waktu—seperti mengubah nama kolom, menambahkan nilai enumerasi, atau mengubah parameter menjadi wajib—dapat dijalankan oleh AI asalkan ada pengamanan ketat untuk mencegah kerusakan pada endpoint atau skema yang sudah ada. CLI Apidog menyediakan mekanisme perlindungan seperti validasi lokal, cabang AI terisolasi, dan proses penggabungan yang harus melalui tinjauan.
Artikel ini melengkapi panduan yang sebelumnya membahas cara agent AI membuat dokumentasi API baru. Membuat sumber daya baru umumnya bersifat aditif dan rendah risiko, tetapi memperbarui kontrak yang sudah ada memerlukan kontrol lebih ketat. Perubahan yang tidak lengkap bisa menghapus data dari spesifikasi. Apa yang dimaksud dengan "memperbarui spesifikasi" melalui CLI? Dalam Apidog, spesifikasi mencakup endpoint dan skema data dalam sebuah proyek. Operasi utamanya adalah pembaruan endpoint (mengubah path, parameter, atau respons), pembaruan skema (mengubah model data yang dirujuk oleh endpoint), dan impor (mengimpor file OpenAPI lengkap dan menyelaraskannya dengan proyek). Sebelum mendelegasikan perintah-perintah ini kepada agent, ingat dua aturan utama. Pertama, pembaruan menggantikan objek yang dikirim, tidak melakukan penggabungan otomatis pada array atau properti. Kedua, modifikasi harus dilakukan dalam cabang AI, lalu ditinjau sebelum digabungkan. Poin kritisnya adalah pembaruan menggantikan seluruh objek Perintah pembaruan tidak berfungsi seperti JSON Patch. Perintah ini menulis ulang bidang yang diberikan dan tidak menggabungkan elemen array berdasarkan ID. Misalnya, mengirim array parameters yang berisi satu parameter tidak akan mengubah parameter tersebut; ini akan menggantikan seluruh array dan menghapus parameter lain. Gunakan pola loop baca → modifikasi → validasi → tulis: 1. Ambil sumber daya lengkap dengan `apidog endpoint get <endpointId> --project <projectId>`. 2. Edit objek lengkap secara lokal, pertahankan bidang yang tidak terkait dengan perubahan. 3. Validasi payload lengkap menggunakan `apidog cli-schema validate endpoint-create --file ./endpoint-full.json`. 4. Tulis ulang objek lengkap dengan `apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json`. Tambahkan instruksi ini secara eksplisit pada prompt atau aturan agent: jangan pernah mengirim objek parsial ke pembaruan. Selalu ambil sumber daya lengkap, modifikasi secara lokal, validasi, lalu kirim kembali secara utuh. Aturan ini mencegah penghapusan diam-diam atas bidang, parameter, atau properti skema.
Bekerja dalam cabang AI Hindari memberikan akses langsung ke cabang utama. Cabang AI mengisolasi perubahan agent hingga disetujui oleh manusia, mirip dengan pull request untuk kontrak API. Langkah 1: buat cabang AI `apidog branch create --project <projectId> --type ai --from main --name "ai/20260713-from-main-refund-fields"`. Gunakan konvensi penamaan yang mudah dibaca, misalnya `ai/AAAAMMJJ-dari-fitur`. Nilai `--from` harus mengarah ke cabang utama atau cabang sprint biasa, bukan cabang umum. Cabang AI yang tidak memiliki perbedaan dengan cabang sumbernya akan diarsipkan otomatis setelah 24 jam. Langkah 2: impor sumber daya yang sudah ada dengan `pick-to` Cabang AI dimulai kosong dan tidak mengkloning sumber daya dari cabang sumber secara otomatis. Sebelum mengubah atau menghapus endpoint atau skema yang sudah ada, impor terlebih dahulu: `apidog branch pick-to --project <projectId> --type ai --from main --to "ai/20260713-from-main-refund-fields" --endpoint-ids <ids>`. Langkah ini hanya diperlukan untuk sumber daya yang sudah ada yang akan dimodifikasi atau dihapus. Sumber daya yang dibuat langsung oleh agent dalam cabang AI tidak perlu diimpor sebelumnya. Langkah 3: lakukan perubahan dalam cabang Tambahkan flag `--branch` ke semua perintah baca dan tulis: `apidog endpoint get <endpointId> --project <projectId> --branch "ai/20260713-from-main-refund-fields"`. Gunakan `apidog endpoint update` dengan flag cabang yang sama. Cabang utama tetap tidak tersentuh; jika agent melakukan kesalahan, dampaknya terbatas pada cabang terisolasi yang dapat dibuang. Langkah 4: tinjau lalu gabungkan Cabang AI tidak pernah digabungkan secara otomatis. Setelah pekerjaan selesai, tinjau perubahan sebelum mengintegrasikannya. Gunakan `apidog branch merge --project <projectId> --type ai --from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>`. Jika cabang target dilindungi, gunakan permintaan penggabungan (`merge-request`) lalu setujui di klien Apidog. Contoh praktis: mengubah nama bidang skema tanpa menghapus yang lain Misalkan Anda perlu mengubah nama `amount` menjadi `amountCents` dalam skema Refund dan mengubahnya menjadi tipe integer. Instruksikan agent: "Ubah nama bidang `amount` pada skema Refund menjadi `amountCents`, ubah ke tipe integer, pertahankan semua bidang lain, dan validasi objek sebelum menulis." Agent akan memulai dengan mengambil skema lengkap dari cabang AI: `apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"`. Kemudian modifikasi `jsonSchema` lengkap, memperbarui properti yang diperlukan dan nama bidang.
Bagi ekosistem pengembangan perangkat lunak di Indonesia, pendekatan ini sangat relevan. Banyak startup dan perusahaan lokal masih mengandalkan dokumentasi API manual yang rentan terhadap human error. Otomatisasi berbasis AI dapat mempercepat siklus pengembangan, mengurangi bug, dan meningkatkan kolaborasi antar tim. Alat seperti Apidog mulai populer di pasar regional, dan kemampuan agent AI untuk mengelola perubahan API secara aman dapat mendorong adopsi yang lebih luas di perusahaan-perusahaan teknologi Indonesia yang ingin meningkatkan praktik CI/CD mereka.
Secara keseluruhan, panduan ini menunjukkan pergeseran dari editing manual ke proses berbasis agent yang terstruktur dan aman. Dengan mengisolasi perubahan dalam cabang AI dan mewajibkan validasi manusia, tim dapat memanfaatkan kecepatan AI tanpa mengorbankan integritas kontrak API. Ke depan, kita dapat mengharapkan integrasi yang lebih mendalam antara agent AI, pipeline CI/CD, dan platform manajemen API low-code, yang pada akhirnya akan membuat pengelolaan API menjadi lebih cerdas dan lebih andal bagi pengembang di seluruh dunia, termasuk di Indonesia.