Un générateur de client vous évite de copier les chemins d'endpoint et les champs de requête dans votre propre bibliothèque. Il peut aussi produire des modèles qui détectent les entrées incorrectes avant qu'une requête ne quitte votre application.
Où obtenir la spec de Bird ?
Téléchargez la spécification publique en JSON ou en YAML.
La référence API de Bird et les générateurs SDK utilisent aussi le bundle public. Enregistrez le fichier téléchargé avec votre configuration de génération pour pouvoir reproduire le client ultérieurement.
La spécification OpenAPI définit comment sont décrits les chemins, les paramètres, l'authentification et les formats de réponse. Votre générateur utilise cette description pour construire des méthodes et des modèles pour son langage cible.
Comment générer un client ?
Utilisez OpenAPI Generator pour produire un client à partir de la spec JSON de Bird. Installez l'outil avant d'exécuter les commandes de téléchargement, de validation et de génération.
Cet exemple génère un client Ruby dans 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-clientUtilisez JSON pour éviter la limite de taille du parseur YAML du générateur. La validation peut afficher des recommandations même lorsqu'elle réussit. Examinez les erreurs avant de générer.
Remplacez ruby par un générateur pris en charge pour un autre langage. Suivez les prérequis d'installation de ce générateur et le README généré pour compiler ou installer le résultat.
Conservez les fichiers générés séparément du code applicatif écrit manuellement. Regénérer dans ce répertoire peut écraser les modifications que vous avez apportées directement au client.
Le guide d'utilisation du générateur documente les options de langage et les fichiers de configuration.
Quelles opérations le client couvrira-t-il ?
Le client couvre les opérations HTTP incluses dans le bundle public de Bird. Une opération sur une autre surface n'obtiendra pas de méthode via la génération de client public.
Par exemple, la rotation de clé API est disponible via une session du tableau de bord ou un grant personnel CLI ou MCP. Elle est absente du bundle public et ne peut pas être appelée avec une clé d'espace de travail API.
La vérification toll-free possède aussi des opérations CLI et MCP en dehors du bundle public. Vérifiez ces surfaces avant de conclure qu'une méthode absente nécessite un travail manuel.
La publication Realtime est une opération HTTP publique. L'abonnement aux événements d'un canal nécessite une connexion WebSocket. Utilisez un client Realtime pour cette partie.
Quelle gestion des requêtes faut-il vérifier ?
Inspectez le runtime généré avant d'ajouter la gestion qu'il ne fournit pas. Différents générateurs et configurations produisent des comportements différents.
| Aspect | Ce qu'il faut vérifier |
|---|---|
| Région | L'hôte sélectionné correspond à la région indiquée dans le préfixe de votre clé. |
| Idempotence | Une même clé est réutilisée pour chaque tentative d'une même écriture. |
| Réessais | Les erreurs temporaires font l'objet de réessais limités qui respectent Retry-After. |
| Pagination | L'itération suit les curseurs jusqu'à ce qu'il ne reste plus de page. |
| Webhooks | La vérification utilise le corps de requête non modifié et contrôle la signature avant le parsing. |
Un paramètre généré ne gère pas nécessairement sa valeur pour vous. Un champ Idempotency-Key nécessite toujours une clé avec la bonne durée de vie, sauf si le runtime en fournit une.
De même, une région serveur configurable ne prouve pas que le client la lit à partir de votre identifiant. Définissez ou vérifiez l'hôte avant d'envoyer une requête.
Faut-il générer un client ou utiliser un Bird SDK ?
Utilisez un Bird SDK lorsque son langage pris en charge et ses dépendances correspondent à votre application. Générez un client lorsque vous avez besoin d'un autre langage ou des conventions de génération de votre organisation.
SDK ou appels directs API compare les langages pris en charge, le comportement de réessai et les délais d'expiration par défaut.
- Bird SDK : utilisez la gestion des requêtes que Bird fournit et maintient.
- Client généré : choisissez votre langage et examinez la gestion du runtime avant le déploiement.
- Types générés uniquement : conservez la gestion des requêtes dans votre couche HTTP existante.
En bref
Téléchargez la spécification publique.
Bird publie la même description API en YAML et en JSON. Le format JSON évite la limite de taille du parseur YAML du générateur.
Générez pour votre langage cible.
OpenAPI Generator valide le fichier JSON téléchargé avant de générer le client.
Vérifiez la gestion des requêtes générée.
Examinez la sélection de région, les réessais, l'idempotence, la pagination et la vérification des webhooks avant de vous fier au client.
Vérifiez une autre surface pour les opérations manquantes.
La rotation de clé API utilise une session du tableau de bord ou un grant personnel CLI ou MCP. Les abonnements Realtime nécessitent un client WebSocket.