Un generador de clientes te ahorra copiar rutas de endpoints y campos de solicitud en tu propia biblioteca. También puede producir modelos que detecten entradas incorrectas antes de que una solicitud salga de tu aplicación.
¿Dónde obtengo la spec de Bird?
Descarga la especificación pública en JSON o YAML.
La referencia API de Bird y los generadores SDK también usan el bundle público. Guarda el archivo descargado junto con tu configuración de generación para poder reproducir el cliente después.
La especificación OpenAPI define cómo se describen rutas, parámetros, autenticación y estructuras de respuesta. Tu generador usa esa descripción para construir métodos y modelos para su lenguaje objetivo.
¿Cómo genero un cliente?
Usa OpenAPI Generator para producir un cliente a partir de la spec JSON de Bird. Instala la herramienta antes de ejecutar los comandos de descarga, validación y generación.
Este ejemplo genera un cliente Ruby en 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 para evitar el límite de tamaño del parser YAML del generador. La validación puede imprimir recomendaciones incluso cuando tiene éxito. Revisa los errores antes de generar.
Reemplaza ruby con un generador compatible para otro lenguaje. Sigue los requisitos de instalación de ese generador y el README generado para compilar o instalar la salida.
Mantén los archivos generados separados del código de aplicación escrito a mano. Regenerar en ese directorio puede sobrescribir las ediciones que hayas hecho directamente en el cliente.
La guía de uso del generador documenta las opciones de lenguaje y los archivos de configuración.
¿Qué operaciones cubrirá el cliente?
El cliente cubre las operaciones HTTP incluidas en el bundle público de Bird. Una operación en otra superficie no obtendrá un método a través de la generación de cliente público.
Por ejemplo, la rotación de claves API está disponible a través de una sesión de dashboard o un grant personal CLI o MCP. Está ausente del bundle público y no se puede invocar con una clave API de espacio de trabajo.
La verificación toll-free también tiene operaciones CLI y MCP fuera del bundle público. Revisa esas superficies antes de concluir que un método ausente requiere trabajo manual.
La publicación Realtime es una operación HTTP pública. Suscribirse a eventos de canal requiere una conexión WebSocket. Usa un cliente Realtime para esa parte.
¿Qué manejo de solicitudes debo revisar?
Inspecciona el runtime generado antes de agregar el manejo que le falte. Distintos generadores y configuraciones proporcionan comportamientos diferentes.
| Aspecto | Qué verificar |
|---|---|
| Región | El host seleccionado coincide con la región en el prefijo de tu clave. |
| Idempotencia | Una clave se reutiliza en los intentos de la misma escritura. |
| Reintentos | Los fallos temporales tienen reintentos limitados que respetan Retry-After. |
| Paginación | La iteración sigue los cursores hasta que no quede ninguna página más. |
| Webhooks | La verificación usa el cuerpo de la solicitud sin modificar y comprueba la firma antes de parsear. |
Un parámetro generado no necesariamente gestiona su valor por ti. Un campo Idempotency-Key sigue necesitando una clave con el tiempo de vida correcto a menos que el runtime proporcione una.
Del mismo modo, una región de servidor configurable no demuestra que el cliente la lea de tu credencial. Establece o verifica el host antes de hacer una solicitud.
¿Debo generar un cliente o usar un Bird SDK?
Usa un Bird SDK cuando su lenguaje soportado y sus dependencias se ajusten a tu aplicación. Genera un cliente cuando necesites otro lenguaje o las convenciones de generación de tu organización.
SDK o llamadas directas API compara los lenguajes soportados, el comportamiento de reintentos y los tiempos de espera predeterminados.
- Bird SDK: usa el manejo de solicitudes que Bird proporciona y mantiene.
- Cliente generado: elige tu lenguaje y revisa el manejo del runtime antes del despliegue.
- Solo tipos generados: mantén el manejo de solicitudes en tu capa HTTP existente.
En resumen
Descarga la especificación pública.
Bird publica la misma descripción API en YAML y JSON. El formato JSON evita el límite de tamaño del parser YAML del generador.
Genera para tu lenguaje objetivo.
OpenAPI Generator valida el JSON descargado antes de generar el cliente.
Revisa el manejo de solicitudes generado.
Revisa la selección de región, reintentos, idempotencia, paginación y verificación de webhooks antes de confiar en el cliente.
Revisa otra superficie en busca de operaciones faltantes.
La rotación de claves API usa una sesión de dashboard o un grant personal CLI o MCP. Las suscripciones Realtime necesitan un cliente WebSocket.