Dépréciations
Bird déprécie trois types d'éléments, et chacun se comporte différemment. Un champ de requête est renommé, et l'ancien nom continue de fonctionner à côté du nouveau. Un paramètre de requête est remplacé par un meilleur filtre, et il continue de fonctionner sans changement. Une structure de corps de requête est remplacée par une nouvelle structure, et l'ancienne reste acceptée. Dans tous les cas, une requête qui en utilise un revient avec un en-tête de réponse Deprecation qui vous en informe.
L'en-tête
Une réponse à une requête contenant un champ, un paramètre ou une structure de corps déprécié inclut :
| En-tête | Valeur |
|---|---|
| Deprecation | La date à laquelle la dépréciation a été annoncée, par exemple @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
La valeur Deprecation indique quand l'ancien nom est devenu déprécié, conformément à la RFC 9745. Elle n'annonce pas de date de suppression.
Les réponses aux requêtes qui n'utilisent que des noms actuels ne contiennent aucun de ces en-têtes. La présence de l'en-tête est donc le signal : si vous ne le voyez jamais, rien de ce que vous envoyez n'est déprécié.
Pas de date de suppression
Bird n'envoie pas d'en-tête Sunset car aucune date de suppression n'est encore disponible. Un nom remplacé n'est supprimé qu'une fois son utilisation terminée. Bird contacte les clients concernés avant la suppression.
Considérez l'en-tête Deprecation comme une invitation à migrer à votre rythme. Il ne déclenche pas de compte à rebours de suppression.
Un champ de requête renommé
Un nom de champ remplacé se comporte exactement comme avant :
- Il est toujours accepté dans les requêtes, et écrit toujours la même valeur.
- Il est toujours renvoyé dans les réponses, à côté du nom qui l'a remplacé.
- Le nom actuel l'emporte si vous envoyez les deux, ce qui vous permet de migrer un point d'appel à la fois sans que l'ancien nom écrase le nouveau.
Les noms de champs renommés sont omis de cette référence, et les SDK officiels n'exposent que les noms actuels. Mettre à jour votre SDK fait donc passer vos requêtes au nom de champ actuel.
Un paramètre de requête déprécié
Un paramètre de requête est déprécié quand un meilleur filtre le remplace. Il se comporte différemment d'un champ renommé sur trois points importants :
- Il reste publié partout. Le retirer de la référence et des SDK casserait les appelants qui l'envoient déjà, donc il conserve sa ligne dans cette référence, son champ dans chaque SDK, son indicateur dans le CLI, et son entrée dans le schéma d'outil MCP. Mettre à jour votre SDK ne vous fait pas migrer.
- Il n'y a pas de volet réponse. Un paramètre de requête n'apparaît jamais que dans la requête, donc rien ne change dans le corps de la réponse et il n'y a pas de nouveau nom à lire en retour.
- Le remplacement peut ne pas être un seul paramètre. Un filtre est parfois remplacé par une paire, donc la description du paramètre indique quoi utiliser à la place plutôt que de pointer vers un unique successeur.
Comme la mise à jour ne vous fait pas migrer, l'en-tête Deprecation est le seul signal que vous recevrez. Consultez la description du paramètre dans cette référence : un paramètre déprécié commence par Deprecated: et indique son remplacement.
Une structure de corps de requête remplacée
Les points de terminaison d'envoi par lot, POST /v1/sms/batches et POST /v1/email/batches, acceptaient autrefois le lot sous forme d'un tableau JSON nu au niveau supérieur. Ils prennent désormais un objet dont le tableau messages contient les mêmes éléments, ce qui est la structure documentée dans cette référence. Une requête dont le corps est encore le tableau nu continue de fonctionner exactement comme avant, et revient avec l'en-tête Deprecation. Les SDK officiels envoient l'objet messages, donc mettre à jour votre SDK fait passer vos requêtes à la structure actuelle.
Migration
- Surveillez l'en-tête Deprecation dans vos réponses.
- Trouvez la requête qui l'a produit, et consultez cette référence pour l'opération afin de voir les noms actuels et la structure de requête.
- Passez au nom ou à la structure actuel. N'envoyez que la forme actuelle une fois la migration faite.
Dépréciations en cours
| Opération | Déprécié | Utiliser à la place |
|---|---|---|
| WhatsApp : lister les messages | paramètre de requête phone_number | to ou from |
| SMS et email : créer un lot de messages | corps de requête tableau nu | un objet avec messages |
Aucun renommage de champ n'est déprécié. Le numéro de téléphone d'un contact est phone_number et l'adresse e-mail du destinataire d'une vérification est email dans to ; toute autre orthographe est rejetée comme erreur de validation, pour chaque opération qui les accepte.
to et from dans la liste de messages WhatsApp correspondent chacun à une extrémité du message, et chacun accepte un numéro de téléphone ou un identifiant utilisateur à portée d'entreprise. phone_number correspondait au contact dans les deux sens, donc une recherche indifférente au sens nécessite les deux filtres, une requête pour chacun.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first email
Obtenir un guide d'implémentation