Een request kan de server bereiken, ook als je applicatie het antwoord nooit ontvangt. Je integratie heeft een beleid voor die onzekerheid nodig voordat ze begint met opnieuw verzenden.
De REST SDK's van Bird bieden die requestafhandeling voor TypeScript, Python, Go en PHP. Swift- en Kotlin-pakketten bedienen Realtime-abonnementen in plaats van de REST API.
Wat doet een Bird SDK?
De SDK verzorgt herhaalbare requestmechanismen, waaronder retries, routing en bescherming tegen duplicaten.
Bij een muterende operatie genereert het een Idempotency-Key en houdt deze vast bij interne retries. Zo kan Bird dezelfde operatie herkennen na een verloren antwoord.
Het probeert tijdelijke fouten opnieuw met backoff die Retry-After respecteert. Een 429 leidt daarom tot een wachttijd vóór de volgende poging. Authenticatie- en validatiefouten vereisen dat je applicatie de oorzaak corrigeert.
Lijsthelpers halen opeenvolgende pagina's op terwijl je itereert. Regionale routing selecteert de host op basis van het prefix van je key. Webhookhelpers verifiëren de onbewerkte requestbody voordat ze het gedecodeerde event teruggeven.
Je applicatie moet nog steeds dubbele bedrijfsacties afwijzen en eigen onafgerond werk herstellen. Idempotency legt de grens uit tussen requestretries en applicatiegaranties.
Wat als er geen getypte methode is voor mijn operatie?
Gebruik de HTTP-verbmethoden van de SDK om een publiek endpoint aan te roepen zonder een speciale getypte methode.
Deze methoden behouden requestafhandeling, inclusief retries en regioselectie. Je levert het pad en de payload uit de API-referentie.
Een ontbrekende getypte methode maakt een operatie niet onbereikbaar. Een andere aanroepmethode verandert niet welke endpoints je credential kan benaderen.
Roteer bijvoorbeeld een API-key via een ingelogde CLI- of MCP-sessie, of gebruik het dashboard. De CLI- of MCP-server vereist autorisatie van een persoon met api_keys:write. Een service die alleen een API-key heeft, kan dit niet uitvoeren.
Wanneer moet ik HTTP rechtstreeks aanroepen?
Roep rechtstreeks aan als de beschikbare SDK's niet bij je taal, runtime of afhankelijkheidsbeleid passen.
Je kunt ook een direct request gebruiken om een endpoint te inspecteren voordat je een clientbibliotheek kiest. Bird gebruikt dezelfde publieke HTTP API voor beide benaderingen.
Genereer een client uit de OpenAPI-specificatie als je gegenereerde modellen in een andere taal wilt. Controleer het runtimegedrag apart, want generators verschillen in wat ze implementeren.
Selecteer bij directe requests de host voor de regio van je key. Hergebruik één idempotency-key bij retries van één operatie. Volg pagineringscursors. Verifieer inkomende webhooksignaturen over de ongewijzigde body.
Stel retry- en timeoutlimieten in, zodat een falende afhankelijkheid een applicatierequest niet oneindig kan openhouden.
Hoe beïnvloeden retries mijn timeout?
Een retry kan de totale aanroep langer laten duren dan de timeout van één poging.
De SDK's staan standaard twee retries toe, wat een aanroep maximaal drie pogingen geeft. TypeScript, Python en Go hanteren standaard een timeout van 60 seconden per poging. Drie verlopen pogingen kunnen daarom ongeveer drie minuten kosten, nog vóór de retrywachttijden.
PHP gebruikt de timeout die op de HTTP-client is geconfigureerd die je injecteert. Stel die daar in zodat het request een begrensde duur heeft.
Stem het retrybudget af op eventuele buitenste deadlines. De conceptengids voor SDK beschrijft configuratienamen en per-aanroep-overrides voor elke taal.
Voeg geen onbeperkte retryloop toe rond de SDK. Afzonderlijke SDK-aanroepen genereren afzonderlijke keys, tenzij je één stabiele idempotency-key meegeeft voor de hele operatie.
Welke integratie moet ik kiezen?
Kies de kleinste hoeveelheid requestafhandeling die je applicatie zelf moet beheren.
- Bird SDK: je taal wordt ondersteund en de afhankelijkheden passen bij je runtime.
- SDK-verbmethode: de operatie is publiek maar heeft geen speciale getypte methode.
- Gegenereerde client: je hebt een andere taal nodig of eigen generatieconventies.
- Directe HTTP: je wilt afhankelijkheden zelf beheren en het requestbeleid zelf implementeren.
Kort gezegd
SDK's nemen terugkerend requestwerk uit handen.
Ze beheren idempotency-keys, retries, regionale routing, paginering en webhookverificatie. Je applicatie blijft verantwoordelijk voor de eigen bedrijfslogica.
Een ontbrekende getypte methode hoeft je niet te blokkeren.
Gebruik de HTTP-verbmethoden van de SDK voor publieke operaties buiten het getypte oppervlak. Requestafhandeling blijft van toepassing.
Gebruik één key voor retries vanuit je applicatie.
Afzonderlijke SDK-aanroepen genereren afzonderlijke idempotency-keys, tenzij je zelf de key voor de operatie meegeeft.
Reken elke poging mee.
Standaard zijn twee retries ingeschakeld. TypeScript, Python en Go laten elke poging apart verlopen. PHP gebruikt de timeout van de HTTP-client.