Una richiesta può raggiungere il server anche quando la tua applicazione non riceve mai la risposta. La tua integrazione ha bisogno di una policy per questa incertezza prima di iniziare a riprovare gli invii.
Gli SDK REST di Bird forniscono questa gestione delle richieste per TypeScript, Python, Go e PHP. I pacchetti Swift e Kotlin servono le sottoscrizioni Realtime anziché le REST API.
Cosa gestisce un Bird SDK?
L'SDK gestisce la meccanica ripetibile delle richieste, inclusi tentativi, routing e protezione dai duplicati.
Per un'operazione mutante, genera un Idempotency-Key e lo mantiene tra i tentativi interni. Questo permette a Bird di riconoscere la stessa operazione dopo una risposta persa.
Ripete i tentativi per errori transitori con backoff che rispetta Retry-After. Un 429 porta quindi a un'attesa prima di un altro tentativo. Gli errori di autenticazione e validazione richiedono comunque che la tua applicazione ne corregga la causa.
Gli helper per le liste recuperano le pagine successive durante l'iterazione. Il routing regionale seleziona l'host dal prefisso della tua chiave. Gli helper per i webhook verificano il corpo grezzo della richiesta prima di restituire l'evento decodificato.
La tua applicazione deve comunque rifiutare le azioni di business duplicate. Deve anche recuperare il proprio lavoro non completato. Idempotency spiega il confine tra i tentativi delle richieste e le garanzie dell'applicazione.
E se non esiste un metodo tipizzato per la mia operazione?
Usa i metodi con verbo HTTP di SDK HTTP per chiamare un endpoint pubblico senza un metodo tipizzato dedicato.
Questi metodi mantengono la gestione delle richieste, inclusi tentativi e selezione della regione. Fornisci il percorso e il payload dal riferimento API.
Un metodo tipizzato assente non rende un'operazione indisponibile. Cambiare il metodo di chiamata non cambia a quali endpoint può accedere la tua credenziale.
Ad esempio, ruota una chiave API tramite una sessione CLI o MCP autenticata, oppure usa la dashboard. Il server CLI o MCP richiede l'autorizzazione di una persona con api_keys:write. Un servizio che possiede solo una chiave API non può eseguire l'operazione.
Quando dovrei chiamare le HTTP direttamente?
Chiama direttamente quando gli SDK disponibili non si adattano al tuo linguaggio, runtime o policy sulle dipendenze.
Puoi anche usare una richiesta diretta per ispezionare un endpoint prima di scegliere una libreria client. Bird usa le stesse HTTP API pubbliche per entrambi gli approcci.
Genera un client dalla specifica OpenAPI se vuoi modelli generati in un altro linguaggio. Verifica il comportamento a runtime separatamente, perché i generatori differiscono in ciò che implementano.
Per le richieste dirette, seleziona l'host per la regione della tua chiave. Riutilizza una chiave di idempotenza tra i tentativi di una singola operazione. Segui i cursori di paginazione. Verifica le firme dei webhook in arrivo sul corpo non modificato.
Imposta limiti di tentativi e timeout in modo che una dipendenza in errore non possa tenere aperta una richiesta dell'applicazione a tempo indeterminato.
Come influiscono i tentativi sul mio timeout?
Un tentativo può far durare la chiamata totale più a lungo del timeout di un singolo tentativo.
Gli SDK consentono due tentativi per impostazione predefinita, dando a una chiamata fino a tre tentativi. TypeScript, Python e Go hanno un timeout predefinito di 60 secondi per tentativo. Tre tentativi scaduti possono quindi consumare circa tre minuti prima di aggiungere le attese tra i tentativi.
PHP usa il timeout configurato sul client HTTP che inietti. Impostalo lì in modo che la richiesta abbia una durata limitata.
Regola il budget di tentativi insieme a qualsiasi deadline esterna. La guida ai concetti SDK descrive i nomi di configurazione e gli override per chiamata per ogni linguaggio.
Non aggiungere un ciclo di tentativi illimitato attorno all'SDK. Chiamate SDK separate generano chiavi separate, a meno che tu non fornisca una chiave di idempotenza stabile per l'intera operazione.
Quale integrazione dovrei scegliere?
Scegli la quantità minima di gestione delle richieste che la tua applicazione deve gestire autonomamente.
- Bird SDK: il tuo linguaggio è supportato e le sue dipendenze si adattano al tuo runtime.
- Metodo con verbo SDK: l'operazione è pubblica ma non ha un metodo tipizzato dedicato.
- Client generato: ti serve un altro linguaggio o le tue convenzioni di generazione.
- HTTP dirette: vuoi controllare le dipendenze e implementare la policy delle richieste in autonomia.
In breve
Gli SDK gestiscono la parte ripetitiva delle richieste.
Gestiscono chiavi di idempotenza, tentativi, routing regionale, paginazione e verifica dei webhook. La tua applicazione resta responsabile delle proprie regole di business.
Un metodo tipizzato mancante non deve bloccarti.
Usa i metodi con verbo HTTP di SDK HTTP per le operazioni pubbliche al di fuori della superficie tipizzata. La gestione delle richieste resta attiva.
Mantieni una sola chiave tra i tentativi dell'applicazione.
Chiamate SDK separate generano chiavi di idempotenza separate, a meno che tu non fornisca la chiave per l'operazione.
Prevedi un budget per ogni tentativo.
Due tentativi sono abilitati per impostazione predefinita. TypeScript, Python e Go applicano il timeout a ogni tentativo separatamente. PHP usa il timeout del client HTTP.