v1 a v2

Búsqueda de Publicaciones de una Lista: estándar v1.1 frente a X API v2

Si has estado trabajando con el endpoint estándar v1.1 GET lists/statuses, el objetivo de esta guía es ayudarte a comprender las similitudes y diferencias entre los endpoints estándar v1.1 y X API v2.

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

Similitudes

Autenticación

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

Dependiendo de la biblioteca/paquete de autenticación que elijas, la autenticación solo de App probablemente sea la forma más sencilla de comenzar y se puede configurar con un encabezado de solicitud sencillo. Para aprender cómo generar un token de acceso de solo App, consulta esta guía de solo App.

Límites de tasa

Standard v1.1	X API v2
/1.1/lists/statuses.json 900 solicitudes por ventana de 15 minutos con OAuth 1.0a User Context 900 solicitudes por ventana de 15 minutos con solo App	/2/lists/:id/tweets 900 solicitudes por ventana de 15 minutos con OAuth 1.0a User Context 900 solicitudes por ventana de 15 minutos con OAuth 2.0 Authorization Code with PKCE 900 solicitudes por ventana de 15 minutos con solo App

Diferencias

URLs de endpoints

• Endpoints estándar v1.1:
  • GET https://api.x.com/1.1/lists/statuses.json (Consultar Tweets de una Lista específica)
• Endpoint de X API v2:
  • GET https://api.x.com/2/lists/:id/tweets (Consultar Tweets de una Lista específica)

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/statuses te permite devolver hasta 5000 Publicaciones por solicitud. Los nuevos endpoints v2 te permiten devolver hasta 100 Publicaciones por solicitud. De forma predeterminada, se devolverán 100 objetos de usuario; para cambiar el número de resultados tendrás que 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 mayores diferencias entre las versiones de endpoints estándar v1.1 y X API v2 es cómo seleccionas qué campos se devuelven en tu payload.

Para los endpoints estándar, recibes muchos de los campos de la respuesta de forma predeterminada y luego tienes la opción de usar parámetros para identificar qué campos adicionales o conjuntos de campos deben devolverse en el payload.

La versión de X API v2 solo entrega por defecto los campos id y text de la Publicación. Para solicitar campos u objetos adicionales, tendrás que usar los parámetros fields y expansions. Cualesquiera campos de Publicación que solicites desde este endpoint se devolverán en el objeto principal de la Publicación. Cualesquiera campos de objetos ampliados se devolverán en un objeto includes dentro de tu respuesta. Luego puedes hacer coincidir cualquier objeto ampliado con el objeto principal de la Publicación haciendo coincidir los IDs del objeto principal y de los objetos ampliados.

Aquí tienes ejemplos de posibles campos de Publicación y expansions:

• attachments
• author_id
• context_annotations
• created_at
• geo
• lang

Endpoint	Expansion
/2/lists/:id/tweets	author_id

Te recomendamos leer más sobre estos nuevos parámetros en sus respectivas guías, o consultar 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 expansión y de campo que tendrás que 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 de 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 hacer referencia a “statuses” Retweeted y Quoted, el JSON de X API v2 hace referencia a Tweets Retweeted y Quoted. 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 incluyen en el payload. Los atributos de Publicación y de 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:

Standard v1.1	X API v2
list_id	id
slug	Sin equivalente
owner_screen_name	Sin equivalente
owner_id	Se solicita con el parámetro expansions con el valor author_id
since_id	Sin equivalente
max_id	Sin equivalente
include_entities	Se solicita con el parámetro tweet.fields con el valor entities
include_rts	Sin equivalente
count	max_results

---

Ejemplos de código

Obtener Publicaciones de una Lista (v2)

cURL

shellscript

curl "https://api.x.com/2/lists/84839422/tweets?tweet.fields=created_at,public_metrics&max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"