Guide d’intégration

Cette page présente plusieurs outils et concepts essentiels à connaître lors de l’intégration des endpoints de recherche de List dans votre système. Nous avons organisé 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 quelques 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 pour 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 utiliser cet endpoint avec du code dans votre langage de programmation préféré ? Nous proposons plusieurs exemples de code sur notre page GitHub que vous pouvez utiliser comme point de départ.

​

Bibliothèques tierces

Tirez parti des bibliothèques tierces mises à disposition par nos communautés pour vous aider à démarrer. Pour trouver une bibliothèque compatible avec les endpoints v2, recherchez l’étiquette de version appropriée.

​

Concepts clés

​

Authentification

Tous les endpoints X API v2 exigent d’authentifier vos requêtes à l’aide d’un ensemble d’identifiants, également appelés clés et jetons. Vous pouvez utiliser Contexte utilisateur OAuth 1.0a, App only ou OAuth 2.0 Autorisation par code avec PKCE pour authentifier vos requêtes vers ces endpoints.

Contexte utilisateur OAuth 1.0a, ce qui signifie que vous devez utiliser un ensemble d’API Key et d’Access Tokens utilisateur pour effectuer une requête avec succès. 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 via 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 pour authentifier vos requêtes.

OAuth 2.0 Autorisation par code avec PKCE offre un meilleur contrôle sur la portée d’une application, ainsi que sur les flux d’autorisation entre plusieurs appareils. OAuth 2.0 vous permet de choisir des portées fines et spécifiques qui vous accordent des autorisations précises pour le compte 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 soit générer un App only token directement au sein d’une App développeur, soit en générer un en utilisant 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 créer un compte développeur, configurer un Project au sein de ce compte, puis créer une App développeur au sein de ce Project. Vous pourrez ensuite retrouver 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 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 au nom de votre App ou au nom d’un utilisateur authentifié. 

Ces endpoints sont soumis à des limites de taux à la fois au niveau de l’App et 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 une App donnée (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 effectuer une recherche de List qu’un certain nombre de fois, toutes Apps développeur confondues.

Le tableau ci-dessous indique les limites de taux pour chaque endpoint.

Endpoint	Méthode HTTP	Limite de taux
/2/lists/:id	GET	75 requêtes par 15 minutes
/2/users/:id/owned_lists	GET	15 requêtes par 15 minutes

Fields et expansions

L’endpoint GET de la X API v2 permet aux utilisateurs de sélectionner exactement quelles data ils souhaitent récupérer depuis l’API à l’aide d’un ensemble d’outils appelés fields et expansions. Le paramètre expansions vous permet d’inclure les objets référencés dans la charge utile. Par exemple, consulter une List par ID vous permet d’obtenir les expansions suivantes :

• owner_id

Le paramètre fields vous permet de sélectionner exactement quels fields au sein des différents objets de data vous souhaitez recevoir. Ces endpoints renvoient principalement des objets List. Par défaut, l’objet List renvoie les fields id et name. Pour recevoir des fields supplémentaires tels que list.created_at ou list.follower_count, vous devrez les demander spécifiquement en utilisant un paramètre list.fields. 

Nous avons ajouté un guide sur l’utilisation conjointe des fields et expansions dans notre X API v2 data dictionary.

 Le tableau ci-dessous présente les fields et expansions disponibles pour ce groupe d’endpoints :

Endpoint	Fields	Expansions
/2/lists/:id	list.fields user.fields	owner_id
/2/users/:id/owned_lists	list.fields user.fields	owner_id

​

Pagination

La recherche des Lists appartenant à un utilisateur peut renvoyer une grande quantité de data. 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’inclure dans une seule réponse. Dans ce cas, les data sont renvoyées sous la forme d’une série de « pages ». Pour en savoir plus, consultez comment paginer les résultats.