Une requête peut atteindre le serveur même si votre application ne reçoit jamais la réponse. Votre intégration a besoin d'une politique pour cette incertitude avant de commencer à réessayer des envois.
Les SDK REST de Bird fournissent cette gestion des requêtes pour TypeScript, Python, Go et PHP. Les paquets Swift et Kotlin servent les abonnements Realtime au lieu de l'REST API.
Que gère un Bird SDK ?
Le SDK gère la mécanique répétitive des requêtes, notamment les réessais, le routage et la protection contre les doublons.
Pour une opération mutante, il génère un Idempotency-Key et le conserve entre les réessais internes. Cela permet à Bird de reconnaître la même opération après une réponse perdue.
Il réessaie les échecs transitoires avec un intervalle progressif qui respecte Retry-After. Un 429 entraîne donc une attente avant la tentative suivante. Les échecs d'authentification et de validation nécessitent que votre application en corrige la cause.
Les helpers de liste récupèrent les pages successives au fil de l'itération. Le routage régional sélectionne l'hôte à partir du préfixe de votre clé. Les helpers de webhook vérifient le corps brut de la requête avant de renvoyer l'événement décodé.
Votre application doit toujours rejeter les actions métier en double. Elle doit aussi reprendre son propre travail inachevé. Idempotency explique la frontière entre les réessais de requête et les garanties applicatives.
Et s'il n'existe pas de méthode typée pour mon opération ?
Utilisez les méthodes de verbe HTTP du SDK pour appeler un endpoint public sans méthode typée dédiée.
Ces méthodes conservent la gestion des requêtes, y compris les réessais et la sélection de région. Vous fournissez le chemin et le payload à partir de la référence API.
L'absence d'une méthode typée ne rend pas une opération indisponible. Changer la méthode d'appel ne change pas les endpoints auxquels votre identifiant peut accéder.
Par exemple, effectuez la rotation d'une clé API via une session CLI ou MCP connectée, ou utilisez le dashboard. Le serveur CLI ou MCP nécessite l'autorisation d'une personne disposant de api_keys:write. Un service ne détenant qu'une clé API ne peut pas effectuer cette opération.
Quand appeler l'HTTP directement ?
Appelez directement quand les SDK disponibles ne correspondent pas à votre langage, votre runtime ou votre politique de dépendances.
Vous pouvez aussi utiliser une requête directe pour inspecter un endpoint avant de choisir une bibliothèque client. Bird utilise la même HTTP API publique pour les deux approches.
Générez un client à partir de la spécification OpenAPI si vous souhaitez des modèles générés dans un autre langage. Vérifiez son comportement à l'exécution séparément, car les générateurs diffèrent dans ce qu'ils implémentent.
Pour les requêtes directes, sélectionnez l'hôte correspondant à la région de votre clé. Réutilisez une clé d'idempotence entre les réessais d'une même opération. Suivez les curseurs de pagination. Vérifiez les signatures de webhook entrantes sur le corps non modifié.
Définissez des limites de réessai et de délai d'expiration pour qu'une dépendance défaillante ne puisse pas maintenir une requête applicative ouverte indéfiniment.
Comment les réessais affectent-ils mon délai d'expiration ?
Un réessai peut faire durer l'appel total plus longtemps que le délai d'expiration d'une seule tentative.
Les SDK autorisent deux réessais par défaut, ce qui donne jusqu'à trois tentatives par appel. TypeScript, Python et Go appliquent par défaut un délai d'expiration de 60 secondes par tentative. Trois tentatives expirées peuvent donc consommer environ trois minutes avant d'ajouter les temps d'attente entre réessais.
PHP utilise le délai d'expiration configuré sur le client HTTP que vous injectez. Définissez-le à cet endroit pour que la requête ait une durée bornée.
Ajustez le budget de réessai en fonction de toute échéance externe. Le guide des concepts SDK décrit les noms de configuration et les surcharges par appel pour chaque langage.
N'ajoutez pas de boucle de réessai illimitée autour du SDK. Des appels SDK distincts génèrent des clés distinctes, sauf si vous fournissez une clé d'idempotence stable pour l'ensemble de l'opération.
Quelle intégration choisir ?
Choisissez la plus petite part de gestion des requêtes que votre application doit assumer.
- Bird SDK : votre langage est supporté et ses dépendances conviennent à votre runtime.
- Méthode de verbe SDK : l'opération est publique mais ne dispose pas d'une méthode typée dédiée.
- Client généré : vous avez besoin d'un autre langage ou de vos propres conventions de génération.
- HTTP directe : vous souhaitez contrôler les dépendances et implémenter vous-même la politique de requête.
En bref
Les SDK prennent en charge la mécanique répétitive des requêtes.
Ils gèrent les clés d'idempotence, les réessais, le routage régional, la pagination et la vérification des webhooks. Votre application reste responsable de ses règles métier.
L'absence d'une méthode typée ne vous bloque pas.
Utilisez les méthodes de verbe HTTP du SDK pour les opérations publiques hors de sa surface typée. La gestion des requêtes reste active.
Conservez une seule clé pour les réessais applicatifs.
Des appels SDK distincts génèrent des clés d'idempotence distinctes, sauf si vous fournissez vous-même la clé pour l'opération.
Prévoyez un budget pour chaque tentative.
Deux réessais sont activés par défaut. TypeScript, Python et Go appliquent un délai d'expiration à chaque tentative séparément. PHP utilise le délai d'expiration de son client HTTP.