Avec X API v2, nous avons introduit une nouvelle stratégie de gestion des versions qui aide les développeurs à mieux savoir quand s’attendre à des changements dans les API publiques de X et quand ils devront migrer vers de nouvelles versions.
Les développeurs seront informés des dépréciations, retraits, modifications et ajouts à la X API via nos canaux de communication, afin qu’ils puissent planifier en conséquence l’intégration de ces changements dans leur feuille de route de développement. Toutes les modifications apportées à l’API seront consignées dans le journal des modifications.
La X API comporte actuellement trois versions. Nous recommandons vivement d’utiliser X API v2 lors de la planification de votre intégration, sauf si une fonctionnalité requise par votre cas d’usage n’a pas encore été publiée en v2.
Pour en savoir plus sur chaque version, veuillez consulter les pages suivantes :
- X API v2
- Gnip 2.0 (Enterprise)
Stratégie de versionnage
Le versionnage de la X API est indiqué par des numéros de version déclarés dans le chemin des routes de nos endpoints :
https://api.x.com/2/tweets
Nous visons à publier des versions majeures de la X API en fonction des besoins, mais pas plus d’une fois tous les 12 mois. Une version majeure sera publiée lorsque des changements incompatibles seront introduits dans l’API. Nous publierons des guides de migration lors du lancement d’une nouvelle version majeure afin d’aider les développeurs à passer à la nouvelle version.
Un changement incompatible exige que les développeurs modifient leur code pour préserver les fonctionnalités existantes de leur App. Les changements non incompatibles seront additifs et déployés sur la version la plus récente lorsqu’ils seront prêts, sans nécessiter d’intervention de la part du développeur, sauf si vous souhaitez profiter des nouvelles fonctionnalités.
Si un changement incompatible doit être déployé en cours de cycle (pour des raisons de sécurité ou de confidentialité), il sera appliqué à la version la plus récente.
Modifications incompatibles
Ces changements obligent les développeurs à modifier leur code pour conserver le fonctionnement actuel de leur application.
- Ajout d’un nouveau paramètre obligatoire
- Suppression d’un endpoint existant
- Suppression de tout champ dans la réponse (obligatoire ou facultatif)
- Suppression d’un paramètre de query
- Restructuration du format d’entrée ou de sortie (par exemple, transformer un champ de premier niveau en sous-champ, ou rendre les erreurs intégrées/inline)
- Modification du nom ou du type de données d’un paramètre d’entrée existant ou d’une valeur de sortie
- Modification du nom d’un champ
- Modification du nom de la ressource
- Modification d’un code de réponse
- Modification des types d’erreur
- Modifications des étendues d’autorisation existantes
Modifications rétro-compatibles
- Ajout d’un nouvel endpoint
- Ajout d’un paramètre optionnel
- Ajout d’un nouveau champ de réponse
- Modification du texte des messages d’erreur
- Disponibilité de nouveaux scopes
- « Mise à null » de champs (remplacement de la valeur d’un champ par null pour des raisons de confidentialité/sécurité, en alternative à sa suppression complète)
Dépréciation et retrait
Tout d’abord, voici notre définition de ce que signifient la dépréciation et le retrait pour la X API :
- Dépréciation : La fonctionnalité n’est plus prise en charge par l’équipe. Aucune nouvelle évolution ne sera proposée pour cette fonctionnalité et, en cas de bogues ou de problèmes avec le produit, la probabilité que nous apportions un correctif est extrêmement faible.
- Retrait : La fonctionnalité ne sera plus accessible.
Dans la plupart des cas, dès qu’une nouvelle version est publiée, la version précédente est signalée comme dépréciée. Les versions restent en état de dépréciation pendant une certaine période, après quoi elles sont retirées.
Veuillez rester informé pour en savoir plus sur les futures dépréciations et retraits.