Um gerador de client evita que você copie caminhos de endpoint e campos de requisição para a sua própria biblioteca. Ele também pode produzir modelos que detectam entrada incorreta antes de a requisição sair da sua aplicação.
Onde obtenho a spec da Bird?
Baixe a especificação pública em JSON ou YAML.
A referência API da Bird e os geradores SDK também usam o bundle público. Salve o arquivo baixado junto com a configuração de geração para poder reproduzir o client depois.
A especificação OpenAPI define como caminhos, parâmetros, autenticação e formatos de resposta são descritos. O seu gerador usa essa descrição para construir métodos e modelos para a linguagem de destino.
Como gero um client?
Use o OpenAPI Generator para produzir um client a partir da spec JSON da Bird. Instale a ferramenta antes de executar os comandos de download, validação e geração.
Este exemplo gera um client Ruby em 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-clientUse JSON para evitar o limite de tamanho do parser YAML do gerador. A validação pode imprimir recomendações mesmo quando é bem-sucedida. Revise os erros antes de gerar.
Substitua ruby por um gerador compatível para outra linguagem. Siga os requisitos de instalação desse gerador e o README gerado para compilar ou instalar a saída.
Mantenha os arquivos gerados separados do código de aplicação escrito manualmente. Regenerar nesse diretório pode sobrescrever edições que você fez diretamente no client.
O guia de uso do gerador documenta opções de linguagem e arquivos de configuração.
Quais operações o client cobrirá?
O client cobre as operações HTTP incluídas no bundle público da Bird. Uma operação em outra superfície não receberá um método por meio da geração de client público.
Por exemplo, a rotação de chave API está disponível por meio de uma sessão do dashboard ou de uma concessão pessoal CLI ou MCP. Ela está ausente do bundle público e não pode ser chamada com uma chave API de espaço de trabalho.
A verificação toll-free também tem operações CLI e MCP fora do bundle público. Verifique essas superfícies antes de concluir que um método ausente exige trabalho manual.
A publicação Realtime é uma operação HTTP pública. A assinatura de eventos de canal requer uma conexão WebSocket. Use um client Realtime para essa parte.
Que tratamento de requisições devo verificar?
Inspecione o runtime gerado antes de adicionar o tratamento que ele não possui. Geradores e configurações diferentes fornecem comportamentos diferentes.
| Aspecto | O que verificar |
|---|---|
| Região | O host selecionado corresponde à região no prefixo da sua chave. |
| Idempotência | Uma chave é reutilizada em todas as tentativas da mesma escrita. |
| Retentativas | Falhas temporárias têm retentativas limitadas que respeitam Retry-After. |
| Paginação | A iteração segue cursores até que não reste mais nenhuma página. |
| Webhooks | A verificação usa o corpo da requisição sem alteração e confere a assinatura antes de fazer o parsing. |
Um parâmetro gerado não necessariamente gerencia o seu valor para você. Um campo Idempotency-Key ainda precisa de uma chave com o tempo de vida correto, a menos que o runtime forneça uma.
Da mesma forma, uma região de servidor configurável não prova que o client a lê da sua credencial. Defina ou verifique o host antes de fazer uma requisição.
Devo gerar um client ou usar um Bird SDK?
Use um Bird SDK quando a linguagem e as dependências compatíveis dele se encaixarem na sua aplicação. Gere um client quando você precisar de outra linguagem ou das convenções de geração da sua organização.
SDK ou chamadas API diretas compara as linguagens compatíveis, o comportamento de retentativa e os padrões de timeout.
- Bird SDK: use o tratamento de requisições que a Bird fornece e mantém.
- Client gerado: escolha a sua linguagem e revise o tratamento do runtime antes da implantação.
- Apenas tipos gerados: mantenha o tratamento de requisições na sua camada HTTP existente.
Em resumo
Baixe a especificação pública.
A Bird publica a mesma descrição API em YAML e JSON. O formato JSON evita o limite de tamanho do parser YAML do gerador.
Gere para a linguagem desejada.
O OpenAPI Generator valida o JSON baixado antes de gerar o client.
Verifique o tratamento de requisições gerado.
Revise seleção de região, retentativas, idempotência, paginação e verificação de webhooks antes de confiar no client.
Verifique outra superfície para operações ausentes.
A rotação de chave API usa uma sessão do dashboard ou uma concessão pessoal CLI ou MCP. Assinaturas Realtime precisam de um client WebSocket.