Passer au contenu principal

​
Cohérence entre les endpoints de la X API v2

L’un des principaux aspects de la nouvelle version v2 de la X API est la cohérence entre les endpoints. Cela signifie que les objets renvoyés, les fonctionnalités et les comportements de l’API sont uniformes sur des endpoints similaires. Vous pouvez vous attendre à ce que les éléments suivants soient identiques sur l’ensemble des endpoints :

​
Nommage des chemins

Le nommage des chemins inclut toujours la version de l’endpoint, suivie de la ressource. Ensuite, le chemin peut contenir un ID lié à la ressource précédente, un verbe de sélection qui aide à déterminer quelles données retourner (par exemple, search ou sample), un verbe de diffusion qui indique comment les données sont livrées (par exemple, stream), ou d’autres ressources ayant une relation avec la ressource principale (par exemple, /user/12/tweets). Enfin, vous pouvez ajouter un paramètre de requête à la fin si l’endpoint accepte des paramètres de requête. Voici quelques exemples de la façon dont ces éléments de chemin et de requête peuvent être organisés : /version/resource/id?param1=value&param2=value /version/resource/delivery/selection?param1=value&param2=value Exemples de requêtes réelles : /2/tweets/1067094924124872705?expansions=attachments.media_keys&tweet.fields=author_id /2/users/2244994945?user.fields=created_at,description /2/tweets/search/stream /2/tweets/search/recent?query=snow

​
Schéma JSON

Les réponses aux requêtes sont définies à l’aide de JSON Schema. Cela signifie que les requêtes renvoient systématiquement des ensembles d’objets sous forme de tableaux, chaque élément possédant un id. Les requêtes ne renvoient pas de structures associatives avec des id comme clés.

​
Objet de réponse et paramètres

L’objet renvoyé par défaut est identique pour chaque endpoint de ce type d’objet :
  • Les valeurs de id sont toujours des chaînes.
  • Les paramètres et les champs de réponse utilisent systématiquement l’orthographe américaine.
  • Les champs sont vides ou non renvoyés s’il n’existe aucune valeur.
  • L’objet entities ne contient que les entités extraites du texte du Post : urls, hashtags, mentions et cashtags.
  • Toutes les informations liées aux cards, y compris les champs media_keys et poll_ids, sont renvoyées dans l’objet attachments.
Voici un exemple d’objet de réponse renvoyé par l’endpoint single Post lookup (avec le paramètre tweet.fields défini sur author_id, entities) : 
{
   "data": {
       "id": "1278747501642657792",
       "text": "Cela fait un an que les Developer Labs de Twitter ont été lancés.\n\nAlors que nous préparons la prochaine génération de la #TwitterAPI (très bientôt), découvrez ce que nous avons appris et ce que nous avons changé en cours de route. https://t.co/WvjuEWCa6G",
       "author_id": "2244994945",
       "entities": {
           "urls": [
               {
                   "start": 188,
                   "end": 211,
                   "url": "https://t.co/WvjuEWCa6G",
                   "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html",
                   "display_url": "blog.x.com/developer/en_u…",
                   "images": [
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=orig",
                           "width": 1600,
                           "height": 600
                       },
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=150x150",
                           "width": 150,
                           "height": 150
                       }
                   ],
                   "status": 200,
                   "title": "Un an avec Twitter Developer Labs : ce que nous avons appris et changé",
                   "description": "Les Labs ont été précieux pour nous aider à comprendre ce qui fonctionne bien et ce qui ne fonctionne pas, ce que vous avez aimé et ce que vous n’avez pas aimé.",
                   "unwound_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html"
               }
           ],
           "hashtags": [
               {
                   "start": 106,
                   "end": 117,
                   "tag": "TwitterAPI"
               }
           ]
       }
   }
}

​
Authentification

Tous les endpoints de la X API v2 nécessitent une authentification. Beaucoup d’entre eux acceptent la méthode OAuth 2.0 Bearer Token, qui requiert un Jeton Bearer dans la requête adressée à l’endpoint pour qu’elle aboutisse. Pour les endpoints nécessitant une autorisation afin de créer, manipuler ou récupérer des données pour le compte d’un autre utilisateur, utilisez le Contexte utilisateur OAuth 1.0a. Cela implique de fournir les clés et jetons de votre App développeur API keys and tokens ainsi qu’un ensemble d’Access Tokens utilisateur que vous générez pour l’utilisateur au nom duquel vous effectuez la requête. Le flux OAuth à 3 étapes peut vous aider à récupérer des Access Tokens. Utilisez un outil ou une bibliothèque qui construit automatiquement cet en-tête d’autorisation. Vous trouverez plus d’informations sur l’authentification dans notre documentation sur l’authentification.

​
Champs

L’objet renvoyé par chaque endpoint est condensé. Pour offrir aux développeurs davantage de souplesse dans la personnalisation de la réponse renvoyée par l’API, le paramètre fields permet de demander les champs souhaités. Les champs restent cohérents d’un endpoint à l’autre. L’Objet Post renverra les mêmes champs sur tous les endpoints où l’Objet Post est retourné. Le même ensemble de champs peut être demandé sur des endpoints similaires. Par exemple, les mêmes champs de Post peuvent être demandés dans la consultation de Posts et pour le Post épinglé développé dans la consultation d’utilisateurs.

​
Expansions

Lorsque cela est approprié, des expansions sont disponibles pour tous les champs id imbriqués (par exemple, tous les champs nommés *_id, tels que author_id). Des expansions sont également disponibles pour tous les champs qui comportent un id qui n’est pas l’identifiant de niveau supérieur de l’objet en cours. Par exemple, dans la recherche de Posts, le Post est l’objet en cours avec le champ id comme identifiant de niveau supérieur. Les champs author_id ou referenced_tweets.id peuvent être développés en objets utilisateur complets ou en Objets Post en ajoutant ces valeurs séparées par des virgules au paramètre expansions. Veuillez signaler toute incohérence que vous constatez, liée à ces fields.
⌘I