Eine Anfrage kann den Server erreichen, auch wenn Ihre Anwendung die Antwort nie erhält. Ihre Integration braucht eine Strategie für diese Unsicherheit, bevor sie mit Sende-Retries beginnt.
Die REST-SDKs von Bird liefern diese Anfrageverarbeitung für TypeScript, Python, Go und PHP. Die Swift- und Kotlin-Pakete bedienen Realtime-Subscriptions statt der REST API.
Was übernimmt ein Bird SDK?
Das SDK übernimmt wiederholbare Anfrage-Mechanik, einschließlich Retries, Routing und Duplikatschutz.
Bei einer schreibenden Operation erzeugt es einen Idempotency-Key und behält ihn über interne Retries hinweg bei. So kann Bird dieselbe Operation nach einer verlorenen Antwort erkennen.
Es wiederholt vorübergehende Fehler mit Backoff, das Retry-After respektiert. Ein 429 führt daher zu einer Wartezeit vor dem nächsten Versuch. Authentifizierungs- und Validierungsfehler erfordern weiterhin, dass Ihre Anwendung deren Ursache behebt.
Listen-Helfer rufen aufeinanderfolgende Seiten ab, während Sie iterieren. Das Region-Routing wählt den Host anhand des Präfixes Ihres Schlüssels. Webhook-Helfer verifizieren den unveränderten Request-Body, bevor sie das dekodierte Ereignis zurückgeben.
Ihre Anwendung muss weiterhin doppelte Geschäftsaktionen ablehnen. Außerdem muss sie ihre eigene unvollständige Arbeit wiederherstellen. Idempotenz erklärt die Grenze zwischen Anfrage-Retries und Anwendungsgarantien.
Was, wenn es keine typisierte Methode für meine Operation gibt?
Verwenden Sie die HTTP-Verb-Methoden des SDK, um einen öffentlichen Endpunkt ohne dedizierte typisierte Methode aufzurufen.
Diese Methoden behalten die Anfrageverarbeitung bei, einschließlich Retries und Regionswahl. Sie liefern Pfad und Payload aus der API-Referenz.
Eine fehlende typisierte Methode macht eine Operation nicht unerreichbar. Ein Wechsel der Aufrufmethode ändert nicht, auf welche Endpunkte Ihre Anmeldedaten Zugriff haben.
Zum Beispiel können Sie einen API-Schlüssel rotieren über eine angemeldete CLI- oder MCP-Sitzung, oder Sie verwenden das Dashboard. Der CLI- oder MCP-Server benötigt die Autorisierung einer Person mit api_keys:write. Ein Dienst, der nur einen API-Schlüssel besitzt, kann die Operation nicht ausführen.
Wann sollte ich HTTP direkt aufrufen?
Rufen Sie direkt auf, wenn die verfügbaren SDKs nicht zu Ihrer Sprache, Laufzeitumgebung oder Abhängigkeitsrichtlinie passen.
Sie können auch eine direkte Anfrage verwenden, um einen Endpunkt zu untersuchen, bevor Sie sich für eine Client-Bibliothek entscheiden. Bird verwendet dieselbe öffentliche HTTP API für beide Ansätze.
Generieren Sie einen Client aus der OpenAPI-Spezifikation, wenn Sie generierte Modelle in einer anderen Sprache benötigen. Prüfen Sie das Laufzeitverhalten separat, da sich Generatoren darin unterscheiden, was sie implementieren.
Wählen Sie bei direkten Anfragen den Host für die Region Ihres Schlüssels. Verwenden Sie einen Idempotenzschlüssel über alle Retries einer Operation hinweg. Folgen Sie Paginierungs-Cursorn. Verifizieren Sie eingehende Webhook-Signaturen anhand des unveränderten Bodys.
Setzen Sie Retry- und Timeout-Limits, damit eine fehlschlagende Abhängigkeit eine Anwendungsanfrage nicht unbegrenzt offen halten kann.
Wie wirken sich Retries auf mein Timeout aus?
Ein Retry kann dazu führen, dass der gesamte Aufruf länger dauert als das Timeout eines einzelnen Versuchs.
Die SDKs erlauben standardmäßig zwei Retries, sodass ein Aufruf bis zu drei Versuche hat. TypeScript, Python und Go verwenden standardmäßig ein 60-Sekunden-Timeout pro Versuch. Drei Versuche mit Timeout können daher etwa drei Minuten verbrauchen, bevor Retry-Wartezeiten hinzukommen.
PHP verwendet das Timeout, das auf dem von Ihnen injizierten HTTP-Client konfiguriert ist. Setzen Sie es dort, damit die Anfrage eine begrenzte Dauer hat.
Passen Sie das Retry-Budget zusammen mit einer äußeren Frist an. Der SDK-Konzeptleitfaden beschreibt Konfigurationsnamen und Pro-Aufruf-Überschreibungen für jede Sprache.
Fügen Sie keine unbegrenzte Retry-Schleife um das SDK hinzu. Separate SDK-Aufrufe erzeugen separate Schlüssel, es sei denn, Sie übergeben einen stabilen Idempotenzschlüssel für die gesamte Operation.
Welche Integration sollte ich wählen?
Wählen Sie das Minimum an Anfrageverarbeitung, das Ihre Anwendung selbst verantworten muss.
- Bird SDK: Ihre Sprache wird unterstützt und die Abhängigkeiten passen zu Ihrer Laufzeitumgebung.
- SDK-Verb-Methode: Die Operation ist öffentlich, hat aber keine dedizierte typisierte Methode.
- Generierter Client: Sie benötigen eine andere Sprache oder eigene Generierungskonventionen.
- Direkte HTTP: Sie möchten Abhängigkeiten kontrollieren und die Anfragestrategie selbst implementieren.
Kurz gesagt
SDKs übernehmen wiederkehrende Anfrage-Mechanik.
Sie verwalten Idempotenzschlüssel, Retries, regionales Routing, Paginierung und Webhook-Verifizierung. Ihre Anwendung bleibt für die Geschäftslogik verantwortlich.
Eine fehlende typisierte Methode muss Sie nicht blockieren.
Nutzen Sie die HTTP-Verb-Methoden des SDK für öffentliche Operationen außerhalb der typisierten Oberfläche. Die Anfrageverarbeitung greift weiterhin.
Verwenden Sie einen Schlüssel über alle Anwendungs-Retries hinweg.
Separate SDK-Aufrufe erzeugen separate Idempotenzschlüssel, es sei denn, Sie übergeben den Schlüssel für die Operation selbst.
Planen Sie für jeden Versuch.
Zwei Retries sind standardmäßig aktiviert. TypeScript, Python und Go begrenzen jeden Versuch einzeln per Timeout. PHP verwendet das Timeout seines HTTP-Clients.