Ein Client-Generator erspart Ihnen das Kopieren von Endpoint-Pfaden und Request-Feldern in eine eigene Bibliothek. Er kann außerdem Modelle erzeugen, die fehlerhafte Eingaben abfangen, bevor ein Request Ihre Anwendung verlässt.
Wo bekomme ich die Spec von Bird?
Laden Sie die öffentliche Spezifikation als JSON oder YAML herunter.
Die API-Referenz und die SDK-Generatoren von Bird verwenden ebenfalls das öffentliche Bundle. Speichern Sie die heruntergeladene Datei zusammen mit Ihrer Generierungskonfiguration, damit Sie den Client später reproduzieren können.
Die OpenAPI-Spezifikation definiert, wie Pfade, Parameter, Authentifizierung und Response-Strukturen beschrieben werden. Ihr Generator nutzt diese Beschreibung, um Methoden und Modelle für seine Zielsprache zu erzeugen.
Wie generiere ich einen Client?
Verwenden Sie OpenAPI Generator, um aus der JSON-Spec von Bird einen Client zu erzeugen. Installieren Sie das Tool, bevor Sie die Download-, Validierungs- und Generierungsbefehle ausführen.
Dieses Beispiel generiert einen Ruby-Client in bird-client:
curl --fail --location https://bird.com/openapi.json --output bird-openapi.json
openapi-generator-cli validate -i bird-openapi.json
openapi-generator-cli generate -i bird-openapi.json -g ruby -o bird-clientVerwenden Sie JSON, um das YAML-Parser-Größenlimit des Generators zu umgehen. Die Validierung kann auch bei Erfolg Empfehlungen ausgeben. Prüfen Sie Fehler vor der Generierung.
Ersetzen Sie ruby durch einen unterstützten Generator für eine andere Sprache. Folgen Sie den Installationsanforderungen dieses Generators und der generierten README, um die Ausgabe zu bauen oder zu installieren.
Halten Sie die generierten Dateien getrennt von handgeschriebenem Anwendungscode. Eine erneute Generierung in dasselbe Verzeichnis kann Änderungen überschreiben, die Sie direkt am Client vorgenommen haben.
Der Nutzungsleitfaden des Generators dokumentiert Sprachoptionen und Konfigurationsdateien.
Welche Operationen deckt der Client ab?
Der Client deckt die HTTP-Operationen ab, die im öffentlichen Bundle von Bird enthalten sind. Eine Operation auf einer anderen Oberfläche erhält keine Methode durch die Public-Client-Generierung.
Zum Beispiel ist die Rotation von API-Keys über eine Dashboard-Sitzung oder einen persönlichen CLI- oder MCP-Grant verfügbar. Sie fehlt im öffentlichen Bundle und kann nicht mit einem Workspace-API-Key aufgerufen werden.
Die Toll-Free-Verifizierung hat ebenfalls CLI- und MCP-Operationen außerhalb des öffentlichen Bundles. Prüfen Sie diese Oberflächen, bevor Sie annehmen, dass eine fehlende Methode manuelle Arbeit erfordert.
Realtime-Publishing ist eine öffentliche HTTP-Operation. Das Abonnieren von Channel-Events erfordert eine WebSocket-Verbindung. Verwenden Sie dafür einen Realtime-Client.
Welche Request-Behandlung sollte ich prüfen?
Untersuchen Sie die generierte Runtime, bevor Sie fehlende Behandlung ergänzen. Verschiedene Generatoren und Konfigurationen liefern unterschiedliches Verhalten.
| Aspekt | Was zu prüfen ist |
|---|---|
| Region | Der gewählte Host stimmt mit der Region im Präfix Ihres Keys überein. |
| Idempotenz | Ein Key wird über alle Versuche desselben Schreibvorgangs hinweg wiederverwendet. |
| Wiederholung | Temporäre Fehler haben begrenzte Wiederholungsversuche, die Retry-After berücksichtigen. |
| Paginierung | Die Iteration folgt Cursors, bis keine weitere Seite mehr vorhanden ist. |
| Webhooks | Die Verifizierung verwendet den unveränderten Request-Body und prüft die Signatur vor dem Parsen. |
Ein generierter Parameter verwaltet seinen Wert nicht unbedingt für Sie. Ein Idempotency-Key-Feld benötigt weiterhin einen Key mit der richtigen Lebensdauer, sofern die Runtime keinen bereitstellt.
Ebenso beweist eine konfigurierbare Serverregion nicht, dass der Client sie aus Ihrem Credential liest. Setzen oder verifizieren Sie den Host, bevor Sie einen Request senden.
Soll ich einen Client generieren oder ein Bird SDK verwenden?
Verwenden Sie ein Bird SDK, wenn dessen unterstützte Sprache und Abhängigkeiten zu Ihrer Anwendung passen. Generieren Sie einen Client, wenn Sie eine andere Sprache oder die Generierungskonventionen Ihrer Organisation benötigen.
SDK oder direkte API-Aufrufe vergleicht die unterstützten Sprachen, das Wiederholungsverhalten und die Timeout-Standardwerte.
- Bird SDK: Nutzen Sie die Request-Behandlung, die Bird bereitstellt und pflegt.
- Generierter Client: Wählen Sie Ihre Sprache und prüfen Sie die Runtime-Behandlung vor dem Deployment.
- Nur generierte Typen: Behalten Sie die Request-Behandlung in Ihrer bestehenden HTTP-Schicht.
Kurz gesagt
Laden Sie die öffentliche Spezifikation herunter.
Bird veröffentlicht dieselbe API-Beschreibung als YAML und JSON. Das JSON-Format umgeht das YAML-Größenlimit des Generators.
Generieren Sie für Ihre Zielsprache.
OpenAPI Generator validiert die heruntergeladene JSON-Datei vor der Client-Generierung.
Prüfen Sie die generierte Request-Behandlung.
Prüfen Sie Regionsauswahl, Wiederholungsversuche, Idempotenz, Paginierung und Webhook-Verifizierung, bevor Sie sich auf den Client verlassen.
Prüfen Sie eine andere Oberfläche auf fehlende Operationen.
Die Rotation von API-Keys erfolgt über eine Dashboard-Sitzung oder einen persönlichen CLI- oder MCP-Grant. Realtime-Subscriptions erfordern einen WebSocket-Client.