v1 vers v2

Recherche de listes : Standard v1.1 comparé à X API v2

Si vous avez travaillé avec les endpoints standard de la v1.1 GET lists/show et  GET lists/ownerships, l’objectif de ce guide est de vous aider à comprendre les similarités et les différences entre les endpoints de recherche de listes de la v1.1 standard et de X API v2.

• Similarités
  • Méthodes d’authentification
  • Limites de taux
• Différences
  • URL des endpoints
  • Exigences pour les Apps et les Projects
  • Limites du nombre d’objets de données par requête
  • Formats des données de réponse
  • Paramètres de requête

Points communs

Authentification

Les deux versions de l’endpoint prennent en charge à la fois le contexte utilisateur OAuth 1.0a et le mode App only. Par conséquent, si vous utilisiez auparavant l’un des endpoints de recherche de Liste standard v1.1, vous pouvez continuer à utiliser la même méthode d’authentification en migrant vers la version X API v2.

Selon la bibliothèque ou le package d’authentification que vous utilisez, l’authentification App only est probablement le moyen le plus simple pour commencer et peut être configurée avec un simple en-tête de requête. Pour savoir comment générer un jeton d’accès App only, consultez ce guide App only.

Limites de taux

Standard v1.1	X API v2
/1.1/lists/show.json 75 requêtes par fenêtre de 15 minutes avec contexte utilisateur OAuth 1.0a 75 requêtes par fenêtre de 15 minutes avec App only	/2/lists/:id 75 requêtes par fenêtre de 15 minutes avec contexte utilisateur OAuth 1.0a 75 requêtes par fenêtre de 15 minutes avec code d’autorisation OAuth 2.0 avec PKCE
/1.1/lists/ownerships.json 15 requêtes par fenêtre de 15 minutes avec contexte utilisateur OAuth 1.0a 15 requêtes par fenêtre de 15 minutes avec App only	/2/users/:id/owned_lists 15 requêtes par fenêtre de 15 minutes avec contexte utilisateur OAuth 1.0a 15 requêtes par fenêtre de 15 minutes avec code d’autorisation OAuth 2.0 avec PKCE 15 requêtes par fenêtre de 15 minutes avec App only

Différences

URL de points de terminaison

• Points de terminaison standard v1.1 :
  • GET https://api.x.com/1.1/lists/show.json (Recherche d’une Liste spécifiée)
  • GET https://api.x.com/1.1/lists/ownerships.json (Recherche des Listes détenues par un utilisateur spécifié)
• Point de terminaison X API v2 :

  • GET https://api.x.com/2/lists/:id (Recherche d’une Liste spécifiée)

  • GET https://api.x.com/2/users/:id/owned_lists (Recherche des Listes détenues par un utilisateur spécifié)

Exigences relatives à l’App et au Project

Les points de terminaison X API v2 exigent que vous utilisiez des informations d’identification provenant d’une developer App associée à un Project lors de l’authentification de vos requêtes. Tous les points de terminaison X API v1.1 peuvent utiliser des informations d’identification provenant d’Apps ou d’Apps associées à un Project.

Limites d’objets de données par requête

Le point de terminaison standard v1.1 /lists/ownerships vous permet de renvoyer jusqu’à 1000 Listes par requête. Les nouveaux points de terminaison v2 vous permettent de renvoyer jusqu’à 100 Listes par requête. Par défaut, 100 objets utilisateur seront renvoyés ; pour modifier le nombre de résultats, vous devez transmettre un paramètre de requête max_results= avec un nombre compris entre 1 et 100 ; vous pouvez ensuite transmettre le next_token renvoyé dans la charge utile de la réponse au paramètre de requête pagination_token dans votre requête suivante.

Format des données de réponse

L’une des plus grandes différences entre les versions de points de terminaison standard v1.1 et X API v2 est la façon dont vous sélectionnez les champs qui sont renvoyés dans votre charge utile.

Pour les points de terminaison standard, vous recevez un grand nombre de champs de réponse par défaut, puis vous avez la possibilité d’utiliser des paramètres pour identifier les champs supplémentaires ou ensembles de champs qui doivent être renvoyés dans la charge utile.

La version X API v2 ne fournit par défaut que les champs id et name de la Liste. Pour demander des champs ou des objets supplémentaires, vous devrez utiliser les paramètres fields et expansions. Tous les champs de Liste que vous demandez à partir de ce point de terminaison seront renvoyés dans l’objet Liste principal. Tout objet Publication ou utilisateur étendu, ainsi que leurs champs, seront renvoyés dans un objet includes au sein de votre réponse. Vous pouvez ensuite faire correspondre les objets étendus à l’objet Liste en faisant correspondre les identifiants présents à la fois dans l’objet utilisateur et dans l’objet Publication étendu. 

Voici des exemples de champs de Liste et d’expansions possibles :

• created_at

• follower_count

• member_count

• owner_id

• description

• private

Point de terminaison	Expansion
/2/lists/:id	owner_id
/2/users/:id/owned_lists	owner_id

Nous vous invitons à en savoir plus sur ces nouveaux paramètres dans leurs guides respectifs, ou en lisant notre guide sur comment utiliser les paramètres fields et expansions. 

Nous avons également élaboré un guide de migration de format de données qui peut vous aider à faire correspondre les champs standard v1.1 aux nouveaux champs v2. Ce guide vous fournira également le paramètre d’expansion et de champ spécifique que vous devrez transmettre avec votre requête v2 pour renvoyer des champs spécifiques. 

En plus des changements concernant la façon dont vous demandez certains champs, X API v2 introduit également de nouvelles structures JSON pour les objets renvoyés par les API, y compris les objets Publication et user.

• Au niveau racine du JSON, les points de terminaison standard renvoient les objets Publication dans un tableau statuses, tandis que X API v2 renvoie un tableau data. 

• Au lieu de faire référence à des « statuses » Retweeted et Quoted, le JSON X API v2 fait référence à des Tweets retweetés et cités. De nombreux champs hérités et obsolètes, tels que contributors et user.translator_type, sont supprimés. 

• Au lieu d’utiliser à la fois favorites (dans l’objet Publication) et favourites (dans l’objet user), X API v2 utilise le terme like. 

• X adopte la convention selon laquelle les valeurs JSON sans valeur (par exemple null) ne sont pas écrites dans la charge utile. Les attributs de Publication et d’utilisateur ne sont inclus que s’ils ont des valeurs non nulles.

Paramètres de requête

Les paramètres de requête standard v1.1 suivants ont des équivalents dans X API v2 :

Recherche de Liste par ID

Standard v1.1	X API v2
list_id	id
slug	Aucun équivalent
owner_screen_name	Aucun équivalent
owner_id	Requis via le paramètre expansions/fields

Recherche de Liste détenue par un utilisateur

Standard v1.1	X API v2
user_id	id
screen_name	Aucun équivalent
count	max_results
cursor	pagination_token