v1 a v2

Búsqueda de listas: versión estándar v1.1 comparada con X API v2

Si has estado trabajando con los endpoints estándar v1.1 GET lists/show y GET lists/ownerships, el objetivo de esta guía es ayudarte a entender las similitudes y diferencias entre la versión estándar v1.1 y los endpoints de búsqueda de listas de X API v2.

• Similitudes
  • Métodos de autenticación
  • Límites de tasa
• Diferencias
  • URL de los endpoints
  • Requisitos de App y Proyecto
  • Límites de objetos de datos por cada solicitud
  • Formatos de datos de respuesta
  • Parámetros de solicitud

Similitudes

Autenticación

Ambas versiones del endpoint admiten tanto OAuth 1.0a User Context como App only. Por lo tanto, si antes estabas usando uno de los endpoints estándar de consulta de Listas de v1.1, puedes seguir usando el mismo método de autenticación si migras a la versión de X API v2.

Según la biblioteca o paquete de autenticación que utilices, la autenticación App only probablemente sea la forma más sencilla de empezar y se puede configurar con un encabezado de solicitud sencillo. Para aprender a generar un token de acceso App only, consulta esta guía de App only.

Límites de tasa

Standard v1.1	X API v2
/1.1/lists/show.json 75 solicitudes por ventana de 15 minutos con OAuth 1.0a User Context 75 solicitudes por ventana de 15 minutos con App only	/2/lists/:id 75 solicitudes por ventana de 15 minutos con OAuth 1.0a User Context 75 solicitudes por ventana de 15 minutos con OAuth 2.0 Authorization Code with PKCE
/1.1/lists/ownerships.json 15 solicitudes por ventana de 15 minutos con OAuth 1.0a User Context 15 solicitudes por ventana de 15 minutos con App only	/2/users/:id/owned_lists 15 solicitudes por ventana de 15 minutos con OAuth 1.0a User Context 15 solicitudes por ventana de 15 minutos con OAuth 2.0 Authorization Code with PKCE 15 solicitudes por ventana de 15 minutos con App only

Diferencias

URLs de endpoints

• Endpoints estándar v1.1:
  • GET https://api.x.com/1.1/lists/show.json (Consultar una Lista específica)
  • GET https://api.x.com/1.1/lists/ownerships.json (Consultar Listas propiedad de un usuario específico)
• Endpoint de X API v2:

  • GET https://api.x.com/2/lists/:id (Consultar una Lista específica)

  • GET https://api.x.com/2/users/:id/owned_lists (Consultar Listas propiedad de un usuario específico)

Requisitos de App y Project

Los endpoints de X API v2 requieren que uses credenciales de una developer App que esté asociada a un Project al autenticar tus solicitudes. Todos los endpoints de X API v1.1 pueden usar credenciales de Apps o de Apps asociadas con un Project.

Límites de objetos de datos por solicitud

El endpoint estándar v1.1 /lists/ownerships permite devolver hasta 1000 Listas por solicitud. Los nuevos endpoints v2 permiten devolver hasta 100 Listas por solicitud. De forma predeterminada, se devolverán 100 objetos de usuario; para cambiar el número de resultados deberás pasar un parámetro de consulta max_results= con un número entre 1 y 100; luego puedes pasar el next_token devuelto en el cuerpo de la respuesta al parámetro de consulta pagination_token en tu siguiente solicitud.

Formato de datos de la respuesta

Una de las diferencias más grandes entre las versiones estándar v1.1 y X API v2 de los endpoints es cómo seleccionas qué campos se devuelven en tu carga útil.

En los endpoints estándar, recibes muchos de los campos de respuesta de forma predeterminada y luego tienes la opción de usar parámetros para identificar qué campos adicionales o conjuntos de campos se deben devolver en la carga útil.

La versión de X API v2 solo entrega los campos id y name de la Lista de forma predeterminada. Para solicitar cualquier campo u objeto adicional, deberás usar los parámetros fields y expansions. Cualquier campo de Lista que solicites desde este endpoint se devolverá en el objeto principal List. Cualquier objeto y campos de Publicación o usuario expandidos se devolverán en un objeto includes dentro de tu respuesta. Luego puedes hacer coincidir cualquier objeto expandido con el objeto List haciendo coincidir los ID ubicados tanto en el usuario como en el objeto de Publicación expandido. 

Aquí tienes ejemplos de posibles campos de Lista y expansions:

• created_at

• follower_count

• member_count

• owner_id

• description

• private

Endpoint	Expansion
/2/lists/:id	owner_id
/2/users/:id/owned_lists	owner_id

Te recomendamos leer más sobre estos nuevos parámetros en sus respectivas guías, o leyendo nuestra guía sobre cómo usar fields y expansions. 

También hemos preparado una guía de migración de formato de datos que puede ayudarte a mapear campos estándar v1.1 a los campos más recientes de v2. Esta guía también te proporcionará el parámetro específico de expansion y field que deberás pasar con tu solicitud v2 para devolver campos específicos. 

Además de los cambios en cómo solicitas ciertos campos, X API v2 también introduce nuevos diseños JSON para los objetos devueltos por las APIs, incluidos los objetos de Post y user.

• En el nivel raíz de JSON, los endpoints estándar devuelven objetos de Publicación en un array statuses, mientras que X API v2 devuelve un array data. 

• En lugar de referirse a “statuses” retuiteados y citados, el JSON de X API v2 se refiere a Tweets retuiteados y citados. Muchos campos heredados y obsoletos, como contributors y user.translator_type, se están eliminando. 

• En lugar de usar tanto favorites (en el objeto de Publicación) como favourites (en el objeto de usuario), X API v2 usa el término like. 

• X está adoptando la convención de que los valores JSON sin valor (por ejemplo, null) no se escriben en la carga útil. Los atributos de Publicación y usuario solo se incluyen si tienen valores no nulos.

Parámetros de solicitud

Los siguientes parámetros de solicitud estándar v1.1 tienen equivalentes en X API v2:

Búsqueda de Lista por ID

v1.1 estándar	X API v2
list_id	id
slug	Sin equivalente
owner_screen_name	Sin equivalente
owner_id	Se solicita con el parámetro expansions/fields

Búsqueda de Lista propiedad de un usuario

Standard v1.1	X API v2
user_id	id
screen_name	Sin equivalente
count	max_results
cursor	pagination_token