Guide d’intégration

​

Guide d’intégration

Cette page présente plusieurs outils et concepts essentiels à connaître lors de l’intégration des endpoints des membres de List dans votre système. Nous avons structuré la page en plusieurs sections :

• Outils utiles
• Concepts clés
• Authentification
• Developer portal, Projects, and Apps
• Limites de taux
• Fields and expansions
• Pagination

​

Outils utiles

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 pour tester un endpoint. Chaque requête Postman inclut tous les paramètres de chemin et de corps afin de vous aider à comprendre rapidement ce qui est disponible. Pour en savoir plus sur nos collections Postman, consultez notre page « Using Postman ». 

​

Exemples de code

Vous souhaitez mettre en place cet endpoint avec du code dans votre langage de programmation préféré ? Nous proposons plusieurs exemples de code à utiliser comme point de départ sur notre page GitHub.

​

Bibliothèques tierces

Tirez parti des bibliothèques tierces de notre communauté pour vous aider à démarrer. Pour trouver une bibliothèque compatible avec les endpoints v2, recherchez l’étiquette de version correspondante.

​

Concepts clés

​

Authentification

Tous les endpoints 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 Contexte utilisateur OAuth 1.0a, OAuth 2.0 Autorisation par code avec PKCE, ou App only pour authentifier vos requêtes pour les endpoints de lookup de Lists. Cependant, vous devez vous authentifier avec Contexte utilisateur OAuth 1.0a ou OAuth 2.0 pour les endpoints de manage de Lists.

Contexte utilisateur OAuth 1.0a signifie que vous devez utiliser un ensemble d’API Keys et d’Access Tokens utilisateur pour effectuer une requête réussie. Les access tokens doivent être associés à l’utilisateur pour le compte duquel vous effectuez la requête. Si vous souhaitez générer un ensemble d’Access Tokens pour un autre utilisateur, celui-ci doit autoriser votre App à l’aide du 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 d’utiliser OAuth 2.0 ou App only pour authentifier vos requêtes.

OAuth 2.0 Autorisation par code avec PKCE offre un meilleur contrôle sur la portée (scope) d’une application et sur les flux d’autorisation multi-appareils. OAuth 2.0 vous permet de choisir des scopes granulaires qui vous donnent des autorisations 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, disponibles dans la section App settings du developer portal.

App only nécessite simplement de transmettre un App only Access Token avec votre requête. Vous pouvez générer un App only Access Token directement au sein d’une App développeur, ou en générer un à l’aide de l’endpoint POST oauth2/token.

App only nécessite simplement de transmettre un App only Access Token avec votre requête. Vous pouvez générer un App only Access Token directement au sein d’une App développeur, ou en générer un à l’aide de l’endpoint POST oauth2/token.

​

developer portal, Projects et Apps développeur

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

​

Limites de taux

Chaque jour, des dizaines de milliers de développeurs envoient des requêtes à la X API. Pour gérer le volume de ces requêtes, des limites de taux sont appliquées à chaque endpoint afin de restreindre le nombre de requêtes que vous pouvez effectuer au nom de votre App ou 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 depuis n’importe quelle App (en utilisant soit l’API Key et la Clé secrète de l’API, soit l’App only Access Token). La limite de taux au niveau de l’utilisateur signifie que l’utilisateur authentifié pour lequel vous effectuez la requête ne peut réaliser une recherche de List qu’un certain nombre de fois, toutes App développeur confondues.

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 par 15 minutes
/2/users/:id/list_memberships	GET	75 requêtes par 15 minutes
/2/lists/:id/members	POST	300 requêtes par 15 minutes
/2/lists/:id/members/:user_id	DELETE	300 requêtes par 15 minutes

​

Champs et expansions

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

• pinned_tweet_id

Le paramètre fields vous permet de sélectionner précisément quels fields des différents objets de données vous souhaitez recevoir. La recherche des membres d’une List 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 devez les demander explicitement à l’aide du paramètre user.fields. 

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

Le tableau ci-dessous présente les fields 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 d’adhésions/membres peut renvoyer un volume important de données. Pour garantir des résultats cohérents et performants à tout moment, nous utilisons la pagination. La pagination est une fonctionnalité des endpoints de la X API v2 qui renvoient plus de résultats qu’il n’est possible d’en fournir dans une seule réponse. Dans ce cas, les données sont renvoyées sous forme de « pages ». En savoir plus sur la façon de paginer les résultats.