DEV Community

Cover image for Cara Agen AI Memperbarui Spesifikasi API dengan Apidog CLI
Walse
Walse

Posted on • Originally published at apidog.com

Cara Agen AI Memperbarui Spesifikasi API dengan Apidog CLI

Mengedit spesifikasi API secara manual adalah pekerjaan yang rumit: mengganti nama field, menambahkan nilai enum, atau memperketat field wajib. Setiap perubahan terlihat kecil, tetapi harus dilakukan pada lokasi yang tepat tanpa merusak endpoint yang mereferensikannya. Ini adalah pekerjaan presisi dan mekanis—jenis tugas yang cocok untuk agen AI, selama Anda memiliki kontrol agar agen tidak merusak seluruh skema.

Coba Apidog hari ini

Dengan CLI Apidog, agen dapat mengubah spesifikasi secara lebih bertanggung jawab: validasi skema sebelum penulisan, cabang terisolasi untuk bekerja, dan merge request untuk ditinjau manusia.

Panduan ini berfokus pada mutasi spesifikasi sebagai pelengkap panduan untuk membiarkan agen membuat dokumentasi API. Membuat dokumentasi bersifat aditif dan cenderung berisiko rendah. Sebaliknya, memperbarui kontrak API yang sudah digunakan membutuhkan guardrail yang jelas.

Apa Arti Memperbarui Spesifikasi di CLI?

Spesifikasi di Apidog berisi endpoint dan skema data dalam sebuah proyek. Ada tiga cara utama untuk memperbaruinya:

  • endpoint update: mengubah path, parameter, atau respons endpoint.
  • schema update: mengubah model data yang direferensikan endpoint.
  • import: mengimpor file OpenAPI baru untuk diselaraskan dengan proyek.

Sebelum memberikan salah satu tugas tersebut kepada agen, pahami dua hal berikut:

  1. Model izin yang digunakan proyek.
  2. Perilaku update yang dapat menghapus data jika payload tidak lengkap.

Jebakan Utama: update Adalah Penggantian Penuh

Ini adalah aturan paling penting untuk agen Anda:

Jangan pernah mengirim objek parsial ke perintah update.

Perintah update di CLI bukan JSON Patch. CLI mengirim field yang diberikan secara langsung dan tidak menggabungkan item array berdasarkan ID.

Misalnya, jika Anda hanya mengirim sebagian array parameters untuk mengubah satu parameter, seluruh array akan diganti oleh payload tersebut. Parameter lain yang tidak dikirim dapat hilang.

Gunakan selalu pola baca → modifikasi → validasi → tulis pada objek lengkap.

# 1. Ambil resource lengkap saat ini
apidog endpoint get <endpointId> --project <projectId>

# 2. Edit struktur lengkap secara lokal.
#    Pertahankan semua field yang tidak diubah.

# 3. Ambil skema CLI dan validasi objek lengkap
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Tulis kembali objek lengkap
apidog endpoint update <endpointId> \
  --project <projectId> \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

Masukkan instruksi berikut ke prompt atau aturan agen:

Jangan pernah mengirim objek parsial untuk update. Selalu ambil resource lengkap, modifikasi field yang diperlukan, validasi payload lengkap, lalu kirim kembali seluruh objek.

Langkah get mencegah field hilang. Langkah cli-schema validate membantu menangkap payload salah sebelum perubahan mencapai proyek.

Jalur Aman: Gunakan Cabang AI

Secara teknis, Anda dapat memberi agen akses edit langsung ke cabang utama. Namun, jangan mulai dari sana.

Gunakan cabang AI agar agen dapat bekerja pada lingkungan terisolasi. Cabang utama tidak berubah sampai Anda meninjau dan menyetujui hasilnya. Polanya mirip pull request untuk spesifikasi API.

Langkah 1: Buat cabang AI 

apidog branch create --project <projectId> --type ai \
  --from main \
  --name "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Gunakan konvensi nama berikut agar asal dan tujuan perubahan mudah dibaca:

ai/YYYYMMDD-from-source-feature
Enter fullscreen mode Exit fullscreen mode

Contoh:

ai/20260713-from-main-refund-fields
Enter fullscreen mode Exit fullscreen mode

Nilai --from harus menunjuk ke cabang utama atau cabang sprint, bukan cabang umum.

Cabang AI tanpa perbedaan dari sumbernya akan diarsipkan otomatis setelah 24 jam. Eksperimen yang ditinggalkan dapat membersihkan dirinya sendiri.

Langkah 2: Impor resource yang akan diedit

Cabang AI dimulai dalam keadaan kosong. Cabang ini tidak otomatis menyalin seluruh isi cabang sumber.

Sebelum agen dapat mengubah endpoint atau skema yang sudah ada, pindahkan resource tersebut ke cabang AI menggunakan pick-to.

apidog branch pick-to --project <projectId> --type ai \
  --from main \
  --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

Langkah ini hanya diperlukan untuk resource yang sudah ada dan ingin dimodifikasi atau dihapus.

Resource baru yang dibuat agen langsung di cabang AI tidak memerlukan pick-to.

Langkah 3: Jalankan perubahan di cabang AI

Setelah resource tersedia, agen dapat memakai siklus baca-modifikasi-tulis dengan opsi --branch.

# Ambil endpoint lengkap dari cabang AI
apidog endpoint get <endpointId> \
  --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

# Setelah payload lengkap dimodifikasi dan divalidasi,
# tulis kembali ke cabang AI
apidog endpoint update <endpointId> \
  --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

Semua perubahan tetap berada di cabang AI. Jika agen membuat kesalahan, cabang utama tidak terdampak.

Langkah 4: Tinjau dan gabungkan

Perubahan di cabang AI tidak ditulis kembali secara otomatis.

Jika cabang target dilindungi, gunakan merge request agar perubahan dapat ditinjau sebelum digabungkan.

apidog merge-request --help
Enter fullscreen mode Exit fullscreen mode

Untuk penggabungan langsung:

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

Tinjau diff terlebih dahulu. Jika cabang utama dilindungi, gunakan merge-request dan setujui perubahan melalui klien Apidog.

Contoh: Mengganti Nama Field dengan Aman

Misalkan Anda ingin mengganti nama field amount menjadi amountCents pada skema Refund, karena nilai kini direpresentasikan sebagai integer dalam satuan cents.

Instruksi untuk agen:

Ganti nama field amount pada skema Refund menjadi amountCents dan ubah tipenya menjadi integer.

Agen harus mengambil skema lengkap dari cabang AI:

apidog schema get <refundSchemaId> \
  --project $PID \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Kemudian, agen mengedit seluruh objek jsonSchema, bukan hanya properti yang berubah:

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": {
        "type": "string"
      },
      "amountCents": {
        "type": "integer"
      },
      "reason": {
        "type": "string"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Perhatikan bahwa orderId dan reason tetap dikirim. Ini penting karena update menggantikan objek, bukan menggabungkannya.

Validasi payload sebelum menulis:

apidog cli-schema validate schema-create --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

Lalu perbarui skema di cabang AI:

apidog schema update <refundSchemaId> \
  --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

Setelah itu, tinjau diff. Perubahan yang diharapkan hanya penggantian amount menjadi amountCents; field lain tidak boleh ikut berubah.

Tandai Breaking Change Sebelum Menggabungkan

Mengganti nama field wajib adalah breaking change. Klien yang masih mengirim amount akan gagal validasi.

Agen seharusnya tidak menggabungkan perubahan seperti ini secara diam-diam. Tambahkan aturan klasifikasi berikut:

Sebelum menggabungkan setiap perubahan spesifikasi, klasifikasikan:

- Tidak merusak:
  field opsional baru, endpoint baru, atau batasan yang dilonggarkan.
  → Ringkas perubahan dan lanjutkan ke permintaan penggabungan.

- Merusak:
  field diganti nama atau dihapus, field wajib baru, atau tipe diperketat.
  → HENTIKAN.
  Laporkan perubahan yang merusak dan endpoint yang terdampak.
  Tunggu persetujuan eksplisit dari manusia.
Enter fullscreen mode Exit fullscreen mode

Cabang AI membuat aturan ini dapat ditegakkan. Agen dapat berhenti dan melaporkan risiko tanpa ada perubahan yang telanjur masuk ke cabang utama.

Memperbarui dari File OpenAPI

Jika perubahan sudah tersedia dalam file OpenAPI—misalnya dihasilkan dari kode, diedit oleh tim lain, atau menjadi sumber kebenaran eksternal—gunakan import daripada mengulang perubahan field satu per satu.

apidog import --project <projectId> \
  --format openapi \
  --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

import menerima OpenAPI 3.x, Swagger 2.0, Postman, dan format lain yang didukung.

Tetap jalankan impor pada cabang AI terlebih dahulu agar Anda bisa meninjau diff sebelum perubahan masuk ke cabang utama.

Setelah penggabungan, ekspor spesifikasi untuk memverifikasi hasil sinkronisasi:

apidog export --project <projectId> \
  --format openapi \
  --oas-version 3.1 \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Gunakan pendekatan ini sesuai sumber kebenaran:

  • Gunakan import jika sumber kebenaran berada di luar Apidog.
  • Gunakan update per resource jika Apidog adalah sumber kebenaran dan Anda membutuhkan perubahan yang presisi.

Ketika Agen Membuat Kesalahan: Rollback

Keuntungan utama cabang AI adalah kesalahan tidak langsung memengaruhi cabang utama.

Jika perubahan agen tidak sesuai, jangan gabungkan cabangnya. Arsipkan cabang tersebut:

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> \
  --type ai
Enter fullscreen mode Exit fullscreen mode

Cabang AI yang tidak memiliki perbedaan juga akan diarsipkan otomatis setelah 24 jam.

Bandingkan dengan agen yang mengedit main langsung: payload update yang buruk langsung aktif, dan Anda harus melakukan pembalikan manual. Dalam alur ini, cabang AI berfungsi sebagai tombol undo.

Catatan tentang Izin

Jika perintah update atau import diblokir, kemungkinan Izin Edit AI Eksternal dimatikan pada proyek.

Gunakan alur cabang AI untuk menjaga perubahan tetap terisolasi dan meminta persetujuan sebelum penggabungan.

Jika Anda memang ingin mengizinkan edit langsung, pengaturannya tersedia di:

Pengaturan Proyek
→ Pengaturan Fitur
→ Pengaturan Fitur AI
Enter fullscreen mode Exit fullscreen mode

Pengaturan ini tersedia pada klien Apidog 2.8.32+.

Saat agen menghadapi batasan izin, jangan biarkan agen mencari jalan keluar secara diam-diam. Laporkan status izin dan minta keputusan manusia.

Kesulitan Umum

  • Pembaruan parsial menghapus field

    update menggantikan objek, bukan menggabungkannya. Ambil objek lengkap, edit, validasi, lalu kirim kembali seluruh objek.

  • Mengedit resource lama di cabang AI tanpa pick-to

    Cabang AI dimulai kosong. Pindahkan resource yang akan diedit sebelum menjalankan update.

  • Menggunakan --from yang salah saat membuat cabang AI

    Sumber harus berupa cabang utama atau cabang sprint, bukan cabang umum.

  • Melewatkan validasi

    Jalankan cli-schema validate sebelum menulis. Ini membantu menangkap payload salah bentuk di mesin lokal.

  • Menggabungkan breaking change secara diam-diam

    Tambahkan klasifikasi perubahan sebagai checkpoint eksplisit dalam instruksi agen.

FAQ

Bisakah agen mengedit cabang utama secara langsung?

Bisa, jika Izin Edit AI Eksternal diaktifkan. Namun, memulai dari cabang AI lebih aman karena tidak ada perubahan yang masuk ke main sebelum Anda menyetujui penggabungan.

Gunakan edit langsung hanya untuk otomatisasi berisiko rendah dan tingkat kepercayaan tinggi.

Apa perbedaan branch merge dan merge-request?

branch merge langsung menulis perubahan dan membutuhkan izin edit pada kedua cabang.

merge-request membuat permintaan yang dapat ditinjau. Ini lebih cocok jika cabang utama dilindungi.

Apakah agen memerlukan aplikasi desktop Apidog?

Tidak. CLI dapat berjalan secara standalone.

Aplikasi desktop hanya diperlukan untuk mengaktifkan atau menonaktifkan pengaturan Izin Edit AI Eksternal, yang biasanya dilakukan satu kali.

Bagaimana mencegah agen mengarang nama field?

Gunakan loop berikut:

cli-schema get → get resource → modifikasi → validate → update
Enter fullscreen mode Exit fullscreen mode

Payload yang memakai field yang tidak valid dapat gagal saat validasi lokal, sebelum mencapai proyek.

Kesimpulan

Agen dapat memperbarui spesifikasi API dengan aman jika tiga aturan ini diterapkan:

  1. Agen bekerja pada cabang AI yang terisolasi.
  2. Setiap update menggunakan pola baca-modifikasi-tulis pada objek lengkap.
  3. Manusia meninjau dan menyetujui penggabungan, terutama untuk breaking change.

CLI Apidog menyediakan perintah untuk edit, validasi, peninjauan, dan rollback. Dengan alur ini, perubahan spesifikasi menjadi diff yang dapat diperiksa, bukan risiko yang langsung masuk ke cabang utama.

Unduh Apidog untuk menggunakan CLI, lalu kombinasikan dengan panduan membiarkan agen membuat dokumentasi API agar agen dapat membantu seluruh siklus penulisan dan pemeliharaan spesifikasi.

Top comments (0)