Un generatore di client ti evita di copiare percorsi degli endpoint e campi delle richieste in una libreria tua. Può anche produrre modelli che intercettano input errati prima che la richiesta lasci la tua applicazione.
Dove trovo la spec di Bird?
Scarica la specifica pubblica in JSON o YAML.
Il reference API di Bird e i generatori SDK usano anch'essi il bundle pubblico. Salva il file scaricato insieme alla configurazione di generazione per poter riprodurre il client in seguito.
La specifica OpenAPI definisce come vengono descritti percorsi, parametri, autenticazione e struttura delle risposte. Il generatore usa quella descrizione per costruire metodi e modelli per il linguaggio di destinazione.
Come genero un client?
Usa OpenAPI Generator per produrre un client dalla spec JSON di Bird. Installa lo strumento prima di eseguire i comandi di download, validazione e generazione.
Questo esempio genera un client Ruby 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-clientUsa JSON per evitare il limite di dimensione del parser YAML del generatore. La validazione può stampare raccomandazioni anche quando ha successo. Esamina gli errori prima di generare.
Sostituisci ruby con un generatore supportato per un altro linguaggio. Segui i requisiti di installazione di quel generatore e il README generato per compilare o installare l'output.
Tieni i file generati separati dal codice applicativo scritto a mano. Rigenerare in quella directory può sovrascrivere le modifiche fatte direttamente al client.
La guida all'uso del generatore documenta le opzioni per il linguaggio e i file di configurazione.
Quali operazioni coprirà il client?
Il client copre le operazioni HTTP incluse nel bundle pubblico di Bird. Un'operazione su un'altra superficie non otterrà un metodo tramite la generazione del client pubblico.
Ad esempio, la rotazione delle chiavi API è disponibile tramite una sessione dashboard o un grant personale CLI o MCP. È assente dal bundle pubblico e non può essere chiamata con una chiave API dello spazio di lavoro.
Anche la verifica toll-free ha operazioni CLI e MCP fuori dal bundle pubblico. Controlla quelle superfici prima di concludere che un metodo assente richieda lavoro manuale.
Il publishing Realtime è un'operazione HTTP pubblica. La sottoscrizione agli eventi di canale richiede una connessione WebSocket. Usa un client Realtime per quella parte.
Quale gestione delle richieste devo controllare?
Ispeziona il runtime generato prima di aggiungere la gestione che manca. Generatori e configurazioni diversi forniscono comportamenti diversi.
| Aspetto | Cosa verificare |
|---|---|
| Regione | L'host selezionato corrisponde alla regione nel prefisso della tua chiave. |
| Idempotenza | Una stessa chiave è riutilizzata nei tentativi della stessa scrittura. |
| Tentativi | Gli errori temporanei prevedono tentativi limitati che rispettano Retry-After. |
| Paginazione | L'iterazione segue i cursori finché non rimangono altre pagine. |
| Webhook | La verifica usa il body della richiesta inalterato e controlla la firma prima del parsing. |
Un parametro generato non gestisce necessariamente il suo valore al posto tuo. Un campo Idempotency-Key richiede comunque una chiave con la durata corretta, a meno che il runtime non ne fornisca una.
Allo stesso modo, una regione server configurabile non dimostra che il client la legga dalla tua credenziale. Imposta o verifica l'host prima di effettuare una richiesta.
Devo generare un client o usare un Bird SDK?
Usa un Bird SDK quando il linguaggio supportato e le dipendenze sono adatti alla tua applicazione. Genera un client quando ti serve un altro linguaggio o le convenzioni di generazione della tua organizzazione.
SDK o chiamate API dirette confronta linguaggi supportati, comportamento dei tentativi e timeout predefiniti.
- Bird SDK: usa la gestione delle richieste che Bird fornisce e mantiene.
- Client generato: scegli il tuo linguaggio e verifica la gestione del runtime prima del deploy.
- Solo tipi generati: mantieni la gestione delle richieste nel tuo layer HTTP esistente.
In breve
Scarica la specifica pubblica.
Bird pubblica la stessa descrizione API in YAML e JSON. Il formato JSON evita il limite di dimensione del parser YAML del generatore.
Genera per il linguaggio di destinazione.
OpenAPI Generator valida il file JSON scaricato prima di generare il client.
Controlla la gestione delle richieste generata.
Verifica selezione della regione, tentativi, idempotenza, paginazione e validazione dei webhook prima di affidarti al client.
Controlla un'altra superficie per le operazioni mancanti.
La rotazione delle chiavi API utilizza una sessione dashboard o un grant personale CLI o MCP. Le sottoscrizioni Realtime richiedono un client WebSocket.