Kontrak API lebih baru daripada ingatan model

Contoh kode yang diingat dapat membuat pembaruan pelanggan terlihat mudah. Dalam kasus ilustratif ini, agen menyusunnya dari ingatan. Nama metodenya terdengar masuk akal. Bidang-bidangnya terasa familier. Data uji menerima permintaan tersebut. Namun kontrak penyedia nyata telah berubah setelah contoh itu ditulis.

Kegagalan terjadi sebelum panggilan. Agen memakai ingatan saat memerlukan sumber terkini.

Presentasi tentang agen dan API yang berubah menyarankan mengambil kutipan persis yang menjawab tugas. Prinsip ini sangat berguna dalam integrasi, karena definisi API adalah kontrak yang bergerak, bukan sekadar bacaan latar.

Panggilan yang tampak masuk akal bukan kontrak

Model besar belajar dari kode, dokumentasi, dan diskusi yang dibuat pada tanggal berbeda. Contoh-contoh itu masih berguna untuk struktur dan kebiasaan penulisan. Namun, contoh tersebut tidak membuktikan apa yang diterima penyedia hari ini, pada versi yang dipakai aplikasi dan akun yang tersambung ke sinkronisasi.

Panduan versi API Shopify mendokumentasikan jadwal rilis triwulanan dan catatan perubahan untuk tiap versi. Pengembang dapat memilih versi yang masih didukung, lalu membaca perubahan yang relevan saat memperbarui. Versi dalam permintaan lebih penting daripada ingatan model tentang “API Shopify”.

Referensi Brevo untuk membuat kontak menambah lapisan lain: atribut kustom harus ada dalam akun, dan nilai yang tidak sesuai dengan tipe atribut yang dideklarasikan dapat diabaikan. Skema API umum tidak dapat memberi tahu agen atribut mana yang dibuat akun tertentu ini. Itu memerlukan pencarian atau validasi yang dibatasi pada akun.

Kontrak terkini mempunyai sedikitnya dua bagian: operasi yang dipublikasikan penyedia dan objek yang dikonfigurasi di akun. Agen memerlukan keduanya jika tugas bergantung pada keduanya.

Versi dan cakupan akun harus ikut bersama jawaban yang diambil. Deskripsi operasi yang benar bagi satu versi API dapat salah bagi versi lain. Nama atribut yang benar di satu akun Brevo mungkin tidak ada di akun berikutnya. Sertakan versi yang dipilih dan pengenal akun dalam data uji, lalu gagal jika salah satunya tidak diketahui. Asisten tidak boleh mengatasi ketidakjelasan itu dengan menebak dari contoh yang mirip.

Ambil bagian kecil yang sedang digunakan

Perbaikan yang buruk adalah menempelkan sepuluh ribu definisi operasi ke setiap interaksi agen. Model mendapat lebih banyak teks untuk dicari, lebih banyak kutipan usang yang membingungkan, dan lebih sedikit ruang untuk tugas sebenarnya. Mintalah operasi yang memindahkan catatan ini serta batas yang menentukan apakah ia berhasil.

Untuk pembaruan kontak, bahan relevan mungkin jalur operasi, bidang yang diperbolehkan, pengenal wajib, aturan tipe atribut, dan versi API sekarang. Berikan kutipan itu kepada agen bersama URL sumbernya. Biarkan sisanya tersedia untuk pertanyaan lain.

Panduan API Brevo dari Tajo dapat membantu pembaca mengenal penyedia. Referensi resmi harus menentukan panggilan yang spesifik sebelum kode produksi menggunakannya. Pembaca perlu sumber yang dapat dibuka kembali ketika penyedia mengubah sesuatu.

Repositori dapat menjadikan proses ini dapat diulang. Catat versi yang dikunci, hash spesifikasi yang disimpan, dan tanggal pemeriksaannya. Hash yang berubah tidak membuktikan adanya perubahan yang merusak; hash itu menunjukkan apa yang perlu dibandingkan. Model dapat merangkum perbedaan yang relevan. Pengujian tetap harus menjalankan operasi yang dibutuhkan sinkronisasi agar berfungsi.

Perlakukan permintaan yang dihasilkan sebagai hipotesis dengan tiga pemeriksaan. Pertama, apakah sesuai dengan operasi resmi dan versi yang dikunci? Kedua, apakah akun terhubung mempunyai objek yang diasumsikan permintaan? Ketiga, apakah eksekusi terbatas meninggalkan keadaan yang diharapkan? Pemeriksaan skema menjawab yang pertama, pencarian akun menjawab yang kedua, dan pembacaan setelah penulisan menjawab yang ketiga. Tidak satu pun menggantikan dua lainnya.

1. Operasi penyedia versi · bidang

   Apa yang diterima API resmi

   membatasi
2. Akun terhubung atribut · tipe

   Apa yang ada dalam akun ini

   membatasi
3. Eksekusi terbatas tulis · baca ulang

   Apa yang benar-benar berubah

Pengambilan informasi bukan bukti eksekusi

Keberatan yang wajar adalah: “Dokumentasi resmi dapat tertinggal dari layanan nyata.” Bisa saja. Membacanya perlu, tetapi tidak cukup. Pengujian kontrak harus mengirim permintaan terbatas melalui kode klien yang sama dan memeriksa respons serta keadaan di sistem tujuan. Jika layanan berperilaku berbeda, catat selisih itu dan batasi operasi yang terdampak.

Agen juga perlu berhenti ketika kontrak ambigu. Pemetaan bidang yang ditebak lalu diterapkan pada banyak kontak lebih mahal daripada satu tinjauan terhadap definisi bidang. Panduan mengintegrasikan beberapa alat bisnis dimulai dengan menetapkan sumber kebenaran bagi tiap objek data; menjaga API tetap mutakhir menerapkan disiplin sama pada operasi yang membawa objek tersebut.

Biayanya adalah memelihara referensi dan pengujian terkini. Alternatifnya ialah membayar asumsi usang yang sama pada setiap catatan yang disentuh sinkronisasi.

Model boleh mengingat gagasannya. Model harus membaca kontrak dan memeriksa akun yang akan diubahnya.

Ini tidak harus membuat tiap interaksi lambat. Simpan sementara kutipan khusus beserta versinya dan skema akun sampai ada peristiwa yang diketahui membatalkannya atau jadwal pembaruan yang dipilih. Simpan sumber dan tanggal pengambilan bersama keputusan. Dengan begitu, biaya pembacaan ulang muncul saat kontrak mungkin berubah, bukan pada setiap baris berulang dalam sinkronisasi yang sudah disetujui.