Bazowe adresy URL i regiony

Bird API jest udostępniane z hostów regionalnych. Każde żądanie trafia bezpośrednio do regionu, w którym przechowywane są dane Twojej organizacji. API nie udostępnia globalnego adresu URL płaszczyzny danych.

Kody regionów składają się z dwóch małych liter oznaczających geografię i cyfry instancji (^[a-z]{2}[0-9]+$). us1 i eu1 działają już dziś; schemat pozwala na dodanie przyszłych regionów, takich jak us2 i ap1, bez żadnych zmian po stronie klienta.

Każda organizacja otrzymuje region przy rejestracji. Region jest wykrywany na podstawie Twojej lokalizacji, można go zmienić przed potwierdzeniem i jest niezmienny w v1. Obszar roboczy, klucze API, wiadomości, dane odbiorców i logi zdarzeń pozostają w tym regionie. Nigdy nie są replikowane między regionami. Takie rozdzielenie wspiera zobowiązania dotyczące rezydencji danych, np. przechowywanie i przetwarzanie w UE dla organizacji z UE.

Tylko uwierzytelnianie i administracja kontem (/v1/auth, /v1/admin) operują na globalnie replikowanych danych, dlatego są obsługiwane z hosta nieregionalnego platform.bird.com.

Klucz API koduje swój region w prefiksie: klucze bk_us1_... należą do us1, klucze bk_eu1_... do eu1. Wysyłaj każdy klucz do odpowiadającego mu hosta regionalnego.

Żądanie, które trafi do niewłaściwego regionu, jest odrzucane z kodem 421 Misdirected Request zamiast być przekierowywane. Komunikat błędu wskazuje właściwy host:

{
  "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": "..."
}

Każda odpowiedź API zawiera również nagłówek X-Bird-Region z nazwą regionu, który ją obsłużył. Pomaga to potwierdzić, do którego regionu faktycznie trafiło żądanie.

Oficjalne SDK i CLI odczytują region z prefiksu klucza i wybierają host. Z kluczem bk_eu1_... każde wywołanie trafia do eu1.platform.bird.com bez dodatkowej konfiguracji. Możesz nadpisać wykryty host na potrzeby środowiska testowego: użyj baseUrl w TypeScript SDK, option.WithBaseURL w Go SDK lub --base-url (albo BIRD_API_URL) w CLI.