Guide d'intégration

Cette page présente les outils et les concepts clés pour l’intégration des endpoints des membres de Liste.

---

​

Outils pratiques

Avant d’aborder certains concepts clés qui vous aideront à intégrer cet endpoint, nous vous recommandons de vous familiariser avec :

​

Postman

Postman est un excellent outil que vous pouvez utiliser pour tester un endpoint. Chaque requête Postman inclut tous les paramètres de chemin et de corps de requête afin de vous aider à comprendre rapidement ce qui est à votre disposition. Pour en savoir plus sur nos collections Postman, consultez notre page « Utiliser Postman ».

​

Exemples de code

Vous souhaitez mettre en place cet endpoint avec du code dans votre langage de programmation favori ? Nous proposons quelques exemples de code que vous pouvez utiliser comme point de départ sur notre page GitHub.

​

Bibliothèques tierces

Profitez de l’une des bibliothèques tierces de notre communauté pour vous aider à démarrer. Vous pouvez trouver une bibliothèque compatible avec les endpoints de la v2 en recherchant le tag de version approprié.

---

​

Concepts clés

​

Authentification

Tous les endpoints de X API v2 exigent que vous authentifiiez vos requêtes avec un ensemble d’identifiants, également appelés clés et jetons. Vous pouvez utiliser OAuth 1.0a User Context, OAuth 2.0 Authorization Code with PKCE ou App only pour authentifier vos requêtes pour les endpoints de lookup de Listes. Cependant, vous devez vous authentifier avec OAuth 1.0a User Context ou OAuth 2.0 pour les endpoints de manage des Listes.

Avec OAuth 1.0a User Context, vous devez utiliser un ensemble de clés d’API et de jetons d’accès utilisateur pour effectuer une requête avec succès. Les jetons d’accès doivent être associés à l’utilisateur pour le compte duquel vous effectuez la requête. Si vous souhaitez générer un ensemble de jetons d’accès pour un autre utilisateur, celui-ci doit autoriser votre App en utilisant le flux OAuth à 3 étapes.

Veuillez noter qu’OAuth 1.0a peut être difficile à utiliser. Si vous n’êtes pas familier avec cette méthode d’authentification, nous vous recommandons d’utiliser une bibliothèque, un outil comme Postman, ou OAuth 2.0 ou App only pour authentifier vos requêtes.

OAuth 2.0 Authorization Code with PKCE offre un contrôle plus fin sur la portée d’une application et sur les flux d’autorisation sur plusieurs appareils. OAuth 2.0 vous permet de choisir des portées spécifiques et granulaires qui vous donnent des permissions précises au nom d’un utilisateur.

Pour activer OAuth 2.0 dans votre App, vous devez l’activer dans les paramètres d’authentification de votre App, situés dans la section « App settings » de la Console de développement.

App only exige simplement que vous transmettiez un jeton d’accès App only avec votre requête. Vous pouvez soit générer un jeton d’accès App only directement au sein d’une App développeur, soit en générer un en utilisant l’endpoint POST oauth2/token.

​

Console de développement, Projets et Apps développeur

Pour obtenir un ensemble d’identifiants d’authentification qui fonctionneront avec les endpoints de la X API v2, vous devez créer un compte développeur, configurer un Projet dans ce compte, puis créer une App développeur dans ce Projet. Vous pourrez ensuite trouver vos clés et jetons au sein de votre App développeur.

​

Limites de taux

Chaque jour, plusieurs milliers de développeurs envoient des requêtes à la X API. Pour aider à gérer l’important volume de ces requêtes, des limites de taux sont appliquées à chaque endpoint, ce qui limite le nombre de requêtes que vous pouvez effectuer pour le compte de votre App ou pour le compte d’un utilisateur authentifié.

Les endpoints de consultation (GET) sont soumis à des limites de taux à la fois au niveau de l’App et au niveau de l’utilisateur, tandis que les endpoints de gestion (POST/DELETE) sont limités au niveau de l’utilisateur. La limite de taux au niveau de l’App signifie que vous, en tant que développeur, ne pouvez effectuer qu’un certain nombre de requêtes vers cet endpoint sur une période donnée à partir d’une App donnée (en utilisant soit l’API Key et l’API Secret Key, soit le App only Access Token). La limite de taux au niveau de l’utilisateur signifie que l’utilisateur authentifié pour le compte duquel vous effectuez la requête ne peut effectuer une recherche de Liste qu’un certain nombre de fois, quelle que soit l’App développeur utilisée.

Le tableau ci-dessous présente les limites de taux pour chaque endpoint.

Endpoint	Méthode HTTP	Limite de taux
/2/lists/:id/members	GET	900 requêtes toutes les 15 minutes
/2/users/:id/list_memberships	GET	75 requêtes toutes les 15 minutes
/2/lists/:id/members	POST	300 requêtes toutes les 15 minutes
/2/lists/:id/members/:user_id	DELETE	300 requêtes toutes les 15 minutes

​

Champs et expansions

L’endpoint GET de X API v2 permet aux utilisateurs de sélectionner exactement quelles données ils souhaitent récupérer à partir de l’API grâce à un ensemble de paramètres appelés fields et expansions. Le paramètre expansions vous permet de développer les objets référencés dans le payload. Par exemple, la recherche des membres d’une Liste vous permet d’utiliser les expansions suivantes :

• pinned_tweet_id

Le paramètre fields vous permet de sélectionner exactement quels champs, parmi les différents objets de données, vous souhaitez recevoir. La recherche des membres d’une Liste renvoie principalement des objets utilisateur. Par défaut, l’objet utilisateur renvoie les champs id, name et username. Pour recevoir des champs supplémentaires tels que user.created_at ou user.description, vous devrez les demander explicitement à l’aide d’un paramètre user.fields.

Nous avons ajouté un guide sur l’utilisation des champs et expansions.

Le tableau ci-dessous présente les champs et expansions disponibles pour chaque endpoint de recherche :

Endpoint	Champs	Expansions
/2/lists/:id/members	user.fields, tweet.fields	pinned_tweet_id
/2/users/:id/list_memberships	list.fields, user.fields	owner_id

​

Pagination

La recherche de membres ou d’adhésions peut renvoyer un grand volume de données. Pour garantir que nous renvoyons des résultats cohérents et performants à tout moment, nous utilisons la pagination. La pagination est une fonctionnalité des endpoints de X API v2 qui renvoient plus de résultats qu’il n’est possible d’en inclure au sein d’une seule réponse. Lorsque cela se produit, les données sont renvoyées sous la forme d’une série de « pages ». Pour en savoir plus sur la pagination des résultats, consultez la page Paginer dans les résultats.