Base URL dan region

Bird API dilayani dari host regional. Setiap permintaan langsung menuju region tempat data organisasi Anda disimpan. API tidak menyediakan URL data-plane global.

Kode region terdiri dari dua huruf kecil untuk geografi ditambah satu digit instans (^[a-z]{2}[0-9]+$). us1 dan eu1 sudah aktif; skema ini mengakomodasi region masa depan seperti us2 dan ap1 tanpa perubahan apa pun di sisi klien.

Setiap organisasi ditetapkan ke satu region saat pendaftaran. Region dideteksi dari lokasi Anda, dapat diubah sebelum Anda mengonfirmasi, dan tidak dapat diubah di v1. Workspace, kunci API, pesan, data penerima, dan log peristiwa tetap berada di region tersebut. Data ini tidak pernah direplikasi lintas region. Pemisahan ini mendukung komitmen residensi data seperti penyimpanan dan pemrosesan di EU untuk organisasi EU.

Hanya autentikasi dan administrasi akun (/v1/auth, /v1/admin) yang beroperasi pada data yang direplikasi secara global, sehingga keduanya dilayani dari host non-region platform.bird.com.

Kunci API menyandikan region-nya dalam prefiks: kunci bk_us1_... milik us1, kunci bk_eu1_... milik eu1. Kirim setiap kunci ke host regional yang sesuai.

Permintaan yang mencapai region yang salah ditolak dengan 421 Misdirected Request alih-alih diteruskan. Pesan kesalahan menyebutkan host yang benar:

{
  "type": "misdirected_error",
  "code": "E01010",
  "name": "MisdirectedRequest",
  "message": "Organization belongs to region eu1 but this request reached us1. Send the request to eu1.platform.bird.com.",
  "request_id": "..."
}

Setiap respons API juga menyertakan header X-Bird-Region yang menyebutkan region yang melayaninya, berguna untuk mengonfirmasi region mana yang benar-benar menerima permintaan.

SDK resmi dan CLI mengurai region dari prefiks kunci dan memilih host. Dengan kunci bk_eu1_..., setiap panggilan menuju eu1.platform.bird.com tanpa konfigurasi. Anda dapat mengganti host yang disimpulkan untuk lingkungan pengujian: gunakan baseUrl di SDK TypeScript, option.WithBaseURL di SDK Go, atau --base-url (atau BIRD_API_URL) pada CLI.