Sebuah permintaan bisa sampai ke server meskipun aplikasi Anda tidak pernah menerima responsnya. Integrasi Anda membutuhkan kebijakan untuk ketidakpastian itu sebelum mulai mengulangi pengiriman.
SDK REST dari Bird menyediakan penanganan permintaan tersebut untuk TypeScript, Python, Go, dan PHP. Paket Swift dan Kotlin melayani langganan Realtime, bukan REST API.
Apa yang ditangani Bird SDK?
SDK menangani mekanisme permintaan yang dapat diulang, termasuk retry, routing, dan perlindungan duplikasi.
Untuk operasi yang mengubah data, SDK menghasilkan Idempotency-Key dan mempertahankannya di seluruh retry internal. Ini memungkinkan Bird mengenali operasi yang sama setelah respons hilang.
SDK mengulangi kegagalan sementara dengan backoff yang mematuhi Retry-After. 429 oleh karena itu menyebabkan jeda sebelum percobaan berikutnya. Kegagalan autentikasi dan validasi tetap memerlukan aplikasi Anda untuk memperbaiki penyebabnya.
Helper list mengambil halaman berurutan saat Anda melakukan iterasi. Routing region memilih host dari prefiks kunci Anda. Helper webhook memverifikasi body permintaan mentah sebelum mengembalikan event yang telah didekode.
Aplikasi Anda tetap perlu menolak aksi bisnis duplikat. Aplikasi juga perlu memulihkan pekerjaan yang belum selesai. Idempotency menjelaskan batas antara retry permintaan dan jaminan aplikasi.
Bagaimana jika tidak ada typed method untuk operasi saya?
Gunakan verb method HTTP dari SDK untuk memanggil endpoint publik tanpa typed method khusus.
Method ini tetap menyertakan penanganan permintaan, termasuk retry dan pemilihan region. Anda menyediakan path dan payload dari referensi API.
Tidak adanya typed method tidak membuat operasi menjadi tidak tersedia. Mengubah cara pemanggilan tidak mengubah endpoint mana yang dapat diakses kredensial Anda.
Sebagai contoh, rotasi kunci API melalui sesi CLI atau MCP yang sudah login, atau gunakan dashboard. Server CLI atau MCP memerlukan otorisasi dari seseorang dengan api_keys:write. Layanan yang hanya memiliki kunci API tidak dapat melakukannya.
Kapan saya harus memanggil HTTP secara langsung?
Panggil secara langsung jika SDK yang tersedia tidak cocok dengan bahasa, runtime, atau kebijakan dependensi Anda.
Anda juga dapat menggunakan permintaan langsung untuk memeriksa endpoint sebelum memilih pustaka klien. Bird menggunakan HTTP API publik yang sama untuk kedua pendekatan.
Hasilkan klien dari spesifikasi OpenAPI jika Anda menginginkan model yang di-generate dalam bahasa lain. Periksa perilaku runtime-nya secara terpisah, karena generator berbeda dalam hal yang mereka implementasikan.
Untuk permintaan langsung, pilih host sesuai region kunci Anda. Gunakan kembali kunci idempotensi di seluruh retry satu operasi. Ikuti cursor paginasi. Verifikasi tanda tangan webhook masuk terhadap body yang tidak diubah.
Tetapkan batas retry dan timeout agar dependensi yang gagal tidak membuat permintaan aplikasi tetap terbuka tanpa batas.
Bagaimana retry memengaruhi timeout saya?
Retry dapat membuat total panggilan berlangsung lebih lama dari timeout satu percobaan.
SDK mengizinkan dua retry secara default, sehingga satu panggilan mendapat hingga tiga percobaan. TypeScript, Python, dan Go memiliki timeout default 60 detik per percobaan. Tiga percobaan yang habis waktu dapat menghabiskan sekitar tiga menit sebelum ditambah jeda retry.
PHP menggunakan timeout yang dikonfigurasi pada klien HTTP yang Anda injeksikan. Atur di sana agar permintaan memiliki durasi yang terbatas.
Sesuaikan anggaran retry bersamaan dengan deadline luar. Panduan konsep SDK menjelaskan nama konfigurasi dan override per panggilan untuk setiap bahasa.
Jangan tambahkan loop retry tanpa batas di sekitar SDK. Panggilan SDK yang terpisah menghasilkan kunci yang terpisah kecuali Anda menyediakan satu kunci idempotensi yang stabil untuk seluruh operasi.
Integrasi mana yang harus saya pilih?
Pilih jumlah penanganan permintaan terkecil yang perlu dikelola aplikasi Anda sendiri.
- Bird SDK: bahasa Anda didukung dan dependensinya cocok dengan runtime Anda.
- Verb method SDK: operasinya publik tetapi tidak memiliki typed method khusus.
- Generated client: Anda membutuhkan bahasa lain atau konvensi generation sendiri.
- HTTP langsung: Anda ingin mengontrol dependensi dan mengimplementasikan kebijakan permintaan sendiri.
Singkatnya
SDK menangani mekanisme permintaan yang berulang.
SDK mengelola kunci idempotensi, retry, routing regional, paginasi, dan verifikasi webhook. Aplikasi Anda tetap mengendalikan aturan bisnisnya sendiri.
Tidak adanya typed method bukan penghalang.
Gunakan verb method HTTP dari SDK untuk operasi publik di luar typed surface-nya. Penanganan permintaan tetap berlaku.
Gunakan satu kunci untuk seluruh retry aplikasi.
Panggilan SDK yang terpisah menghasilkan kunci idempotensi yang terpisah, kecuali Anda menyediakan kunci sendiri untuk operasi tersebut.
Perhitungkan setiap percobaan.
Dua retry diaktifkan secara default. TypeScript, Python, dan Go menerapkan timeout pada setiap percobaan secara terpisah. PHP menggunakan timeout dari klien HTTP-nya.