Żądanie może dotrzeć do serwera, nawet gdy Twoja aplikacja nigdy nie otrzyma odpowiedzi. Twoja integracja potrzebuje strategii na tę niepewność, zanim zacznie ponawiać wysyłki.
SDK REST Bird zapewniają tę obsługę żądań dla TypeScript, Python, Go i PHP. Pakiety Swift i Kotlin obsługują subskrypcje Realtime, a nie REST API.
Co obsługuje Bird SDK?
SDK obsługuje powtarzalną mechanikę żądań, w tym ponawianie, routing i ochronę przed duplikatami.
Dla operacji mutującej generuje Idempotency-Key i zachowuje go między wewnętrznymi ponowieniami. Dzięki temu Bird rozpoznaje tę samą operację po utraconej odpowiedzi.
Ponawia przejściowe błędy z wycofaniem uwzględniającym Retry-After. 429 prowadzi więc do oczekiwania przed kolejną próbą. Błędy uwierzytelniania i walidacji nadal wymagają, aby Twoja aplikacja usunęła ich przyczynę.
Helpery list pobierają kolejne strony w miarę iteracji. Routing regionalny wybiera hosta na podstawie prefiksu Twojego klucza. Helpery webhooków weryfikują surowe ciało żądania przed zwróceniem zdekodowanego zdarzenia.
Twoja aplikacja nadal musi odrzucać zduplikowane akcje biznesowe. Musi też odzyskiwać własną niedokończoną pracę. Idempotentność wyjaśnia granicę między ponowieniem żądań a gwarancjami aplikacji.
Co jeśli nie ma typowanej metody dla mojej operacji?
Użyj metod HTTP SDK do wywołania publicznego endpointu bez dedykowanej typowanej metody.
Te metody zachowują obsługę żądań, w tym ponawianie i wybór regionu. Ścieżkę i ładunek podajesz z referencji API.
Brak typowanej metody nie oznacza, że operacja jest niedostępna. Zmiana metody wywołania nie zmienia tego, do których endpointów Twoje dane uwierzytelniające mają dostęp.
Na przykład zrotuj klucz API przez zalogowaną sesję CLI lub MCP albo użyj dashboardu. Serwer CLI lub MCP wymaga autoryzacji od osoby z api_keys:write. Serwis posiadający jedynie klucz API nie może tego wykonać.
Kiedy wywołać HTTP bezpośrednio?
Wywołuj bezpośrednio, gdy dostępne SDK nie pasują do Twojego języka, środowiska uruchomieniowego lub polityki zależności.
Możesz też użyć bezpośredniego żądania, aby zbadać endpoint przed wyborem biblioteki klienckiej. Bird używa tego samego publicznego HTTP API w obu podejściach.
Wygeneruj klienta ze specyfikacji OpenAPI, jeśli chcesz wygenerowane modele w innym języku. Sprawdź jego zachowanie w runtime osobno, bo generatory różnią się tym, co implementują.
W przypadku bezpośrednich żądań wybierz hosta dla regionu swojego klucza. Używaj tego samego klucza idempotentności między ponowieniami jednej operacji. Podążaj za kursorami paginacji. Weryfikuj sygnatury przychodzących webhooków na niezmienionym ciele żądania.
Ustaw limity ponowień i czasu oczekiwania, aby awaria zależności nie mogła trzymać żądania aplikacji otwartego w nieskończoność.
Jak ponowienia wpływają na mój limit czasu?
Ponowienie może sprawić, że całe wywołanie potrwa dłużej niż limit czasu jednej próby.
SDK domyślnie pozwalają na dwa ponowienia, dając wywołaniu do trzech prób. TypeScript, Python i Go domyślnie ustawiają 60-sekundowy limit czasu na próbę. Trzy próby zakończone upływem limitu mogą więc zająć około trzech minut, nie licząc przerw między ponowieniami.
PHP używa limitu czasu skonfigurowanego na wstrzykiwanym kliencie HTTP. Ustaw go tam, aby żądanie miało ograniczony czas trwania.
Dostosuj budżet ponowień do zewnętrznego deadline'u. Przewodnik po koncepcjach SDK opisuje nazwy konfiguracji i nadpisania na poziomie wywołania dla każdego języka.
Nie dodawaj nieograniczonej pętli ponowień wokół SDK. Osobne wywołania SDK generują osobne klucze, chyba że podasz jeden stały klucz idempotentności dla całej operacji.
Którą integrację wybrać?
Wybierz najmniejszy zakres obsługi żądań, który Twoja aplikacja musi realizować samodzielnie.
- Bird SDK: Twój język jest obsługiwany, a zależności pasują do Twojego środowiska uruchomieniowego.
- Metoda SDK: operacja jest publiczna, ale nie ma dedykowanej typowanej metody.
- Wygenerowany klient: potrzebujesz innego języka lub własnych konwencji generowania.
- Bezpośrednie HTTP: chcesz kontrolować zależności i samodzielnie zaimplementować politykę żądań.
W skrócie
SDK obsługują powtarzalną mechanikę żądań.
Zarządzają kluczami idempotentności, ponawianiem, routingiem regionalnym, paginacją i weryfikacją webhooków. Twoja aplikacja nadal odpowiada za własną logikę biznesową.
Brak typowanej metody nie musi Cię blokować.
Użyj metod HTTP SDK dla publicznych operacji spoza jego typowanej powierzchni. Obsługa żądań nadal działa.
Zachowaj jeden klucz między ponowieniami aplikacji.
Osobne wywołania SDK generują osobne klucze idempotentności, chyba że sam podasz klucz dla danej operacji.
Uwzględnij każdą próbę.
Domyślnie włączone są dwa ponowienia. TypeScript, Python i Go limitują czas każdej próby osobno. PHP używa limitu czasu swojego klienta HTTP.