Guide d’intégration

Cette page présente plusieurs outils et concepts clés à connaître lors de l’intégration des endpoints de mise en sourdine à votre système. Nous avons réparti la page en plusieurs sections :

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

​

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 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 à votre disposition. Pour en savoir plus sur nos collections Postman, veuillez consulter notre page “Utiliser Postman”. 

​

Exemples de code

Vous souhaitez configurer cet endpoint avec du code dans votre langage de programmation préféré ? Nous proposons plusieurs 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 v2 en recherchant le tag de version approprié.

​

Concepts fondamentaux

​

Authentification

Tous les endpoints de la 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 le Contexte utilisateur OAuth 1.0a pour authentifier vos requêtes vers cet endpoint.

Contexte utilisateur OAuth 1.0a, ce qui signifie que vous devez utiliser un ensemble d’API Key et des 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 en utilisant le flux OAuth à 3 étapes.

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

​

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 dans ce compte, puis créer une App développeur dans 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 gérer le volume de ces requêtes, des limites de taux sont appliquées à chaque endpoint, ce qui restreint le nombre de requêtes que vous pouvez effectuer au nom de votre App ou d’un utilisateur authentifié.

Ces endpoints sont soumis à des limites au niveau utilisateur, ce qui signifie que l’utilisateur authentifié pour lequel vous effectuez la requête ne peut appeler l’endpoint qu’un certain nombre de fois, et ce, quelle que soit l’App développeur.

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

Endpoint	Méthode HTTP	Limite de taux
/2/users/:id/pinned_lists	POST	50 requêtes par 15 minutes
/2/users/:id/pinned_lists/:list_id	DELETE	50 requêtes par 15 minutes
/2/users/:id/pinned_lists	GET	15 requêtes par 15 minutes

​

Champs et expansions

L’endpoint GET de la X API v2 permet aux utilisateurs de sélectionner précisément 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 le payload. Par exemple, interroger les Lists épinglées permet de récupérer les expansions suivantes :

• owner_id

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

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

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

Endpoint	Champs	Expansions
/2/users/:id/pinned_lists	list.fields user.fields	owner_id