Sign inGet Started

Konsep SDK

SDK TypeScript, Go, Python, dan PHP mengikuti satu desain. Masing-masing memiliki basis yang di-generate berisi tipe dan klien tingkat rendah yang dihasilkan dari spesifikasi OpenAPI Bird. Lapisan yang ditulis manual mengelola siklus hidup permintaan dan mengekspos permukaan yang dikurasi. Halaman ini membahas perilaku bersama mereka. Halaman per bahasa membahas detail idiomatik.

Idempotensi otomatis

Setiap mutasi (POST, PUT, PATCH, DELETE) mendapat header Idempotency-Key yang di-generate otomatis. Kunci dihasilkan sekali per panggilan logis dan digunakan ulang di setiap percobaan ulang. Ini mencegah penulisan yang dicoba ulang diterapkan dua kali. Jika pengiriman kehabisan waktu setelah server memprosesnya, percobaan ulang menerima respons yang tersimpan. Berikan kunci Anda sendiri (idempotencyKey / option.WithIdempotencyKey / idempotency_key per-panggilan) ketika operasi logis mencakup lebih dari satu panggilan SDK, misalnya loop percobaan ulang aplikasi di sekitar SDK. Lihat Idempotensi untuk protokol sisi server.

Percobaan ulang yang aman

Percobaan ulang aktif secara default (maxRetries: 2 di setiap SDK). Klien mencoba ulang kegagalan sementara, termasuk kesalahan jaringan, batas waktu per-percobaan, respons 429, dan respons 5xx yang dapat dicoba ulang. Klien menggunakan exponential backoff dengan jitter dan mengikuti header Retry-After dari server. Kegagalan deterministik (401, 404, 422, dan respons 4xx lainnya) tidak pernah dicoba ulang. Penggunaan ulang kunci idempotensi membuat percobaan ulang mutasi aman. Batas waktu berlaku untuk setiap percobaan (60 detik secara default), sehingga panggilan dengan percobaan ulang bisa memakan waktu lebih lama. PHP menggunakan batas waktu yang diterapkan oleh klien HTTP yang disuntikkan karena PSR-18 tidak memiliki batas waktu per-permintaan yang portabel.

Paginasi

Endpoint daftar menggunakan paginasi berbasis kursor. Setiap SDK mendukung iterasi native, yang mengambil halaman berikutnya secara otomatis. Untuk kontrol kursor manual, gunakan aksesor halaman tunggal. Setiap halaman menyertakan data dan next_cursor; berikan kursor kembali sebagai starting_after untuk melanjutkan.
for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor
Lihat referensi paginasi untuk kursor, limit, dan include_total.

Inferensi region

Kunci Bird API menyandikan region-nya: bk_{region}_{token}. SDK membaca prefiks dan melakukan routing ke https://{region}.platform.bird.com secara otomatis. Opsi region menggantikan region yang diinferensi. baseUrl eksplisit (option.WithBaseURL / base_url) lebih diutamakan dari keduanya dan mendukung pengembangan lokal atau deployment self-hosted. Konstruksi gagal jika kunci tidak cocok dengan format bk_{region}_ dan tidak ada override yang ditetapkan.

Opsi per-panggilan vs konfigurasi khusus konstruksi

Konfigurasi memiliki dua tingkat. Pengaturan identitas dan transport hanya untuk konstruksi: kunci API, base URL atau region, dan klien HTTP atau implementasi fetch. Pengaturan siklus hidup dapat ditetapkan sebagai default konstruksi dan ditimpa per panggilan: timeout, maxRetries, kunci idempotensi, dan header tambahan. TypeScript, Python, dan PHP menggunakan objek opsi di akhir; Go menggunakan opsi option.With… variadik. Header milik SDK (Authorization, User-Agent, Idempotency-Key) lebih diutamakan dari header yang diberikan pemanggil. Default channel, seperti from email default, mengikuti pola yang sama.

Verifikasi webhook

Setiap SDK menyediakan satu titik masuk verifikasi: webhooks.unwrap(rawBody, headers). Ini mengimplementasikan Standard Webhooks dengan HMAC-SHA256 atas payload mentah dan signing secret endpoint Anda. Ini menerima entri tanda tangan bertag v1, menolak timestamp di luar jendela toleransi 5 menit, dan membandingkan tanda tangan dalam waktu konstan. Berikan byte body permintaan mentah persis seperti yang diterima. Parsing dan serialisasi ulang JSON mengubah byte dan membatalkan tanda tangan.
Jika berhasil, unwrap mengembalikan event bertipe yang dibedakan berdasarkan type, seperti email.delivered atau email.bounced. Tipe event yang tidak dikenal tetap diverifikasi dan di-decode, jadi tangani di cabang default Anda. Kegagalan verifikasi adalah error tersendiri (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError); respons dengan 400. Lihat Webhooks untuk pengaturan endpoint dan katalog event.

Langkah selanjutnya

  • Quickstart: Kirim email pertama Anda dalam bahasa dan framework Anda.
  • Webhook dan event: Siapkan endpoint dan jelajahi katalog event di balik unwrap.
  • Referensi API: Tinjau kontrak HTTP yang digunakan oleh setiap SDK.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Dapatkan ringkasan implementasi