Guía de integración

Esta página contiene información sobre varias herramientas y conceptos fundamentales que debes conocer al integrar los endpoints de consulta de List en tu sistema. Hemos dividido la página en un par de secciones:

• Herramientas útiles
• Conceptos clave
• Autenticación
• Portal de desarrolladores, Project y App
• Límites de tasa
• fields y expansions
• Paginación

​

Herramientas útiles

Antes de abordar algunos conceptos clave que le ayudarán a integrar este endpoint, le recomendamos familiarizarse con:

​

Postman

Postman es una excelente herramienta que puedes usar para probar un endpoint. Cada solicitud de Postman incluye todos los parámetros de ruta y de cuerpo para ayudarte a comprender rápidamente qué tienes disponible. Para obtener más información sobre nuestras colecciones de Postman, visita nuestra página “Uso de Postman”. 

​

Ejemplos de código

¿Le interesa configurar este endpoint con código en su lenguaje de programación preferido? Tenemos varios ejemplos de código disponibles que puede usar como punto de partida en nuestra página de GitHub.

​

Bibliotecas de terceros

Aprovecha alguna de las bibliotecas de terceros de nuestra comunidad para ayudarte a comenzar. Puedes encontrar una biblioteca compatible con los endpoints de v2 buscando la etiqueta de versión correspondiente.

​

Conceptos clave

​

Autenticación

Todos los endpoints de X API v2 requieren que autentiques tus solicitudes con un conjunto de credenciales, también conocidas como keys and tokens. Puedes usar Contexto de usuario de OAuth 1.0a, App only o Código de autorización de OAuth 2.0 con PKCE para autenticar tus solicitudes a estos endpoints. 

Contexto de usuario de OAuth 1.0a, lo que significa que debes usar un conjunto de API Key y Access Tokens de usuario para realizar una solicitud correctamente. Los access tokens deben estar asociados con el usuario en cuyo nombre estás realizando la solicitud. Si deseas generar un conjunto de Access Tokens para otro usuario, ese usuario debe autorizar tu App usando el flujo de OAuth de 3 fases.

Ten en cuenta que OAuth 1.0a puede resultar difícil de usar. Si no estás familiarizado con este método de autenticación, te recomendamos usar una library, una herramienta como Postman, o usar OAuth 2.0 para autenticar tus solicitudes.

Código de autorización de OAuth 2.0 con PKCE permite un mayor control sobre el scope de una aplicación y flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir scopes específicos y granulares que te otorgan permisos específicos en nombre de un usuario. 

Para habilitar OAuth 2.0 en tu App, debes activarlo en la configuración de autenticación de tu App, ubicada en la sección App settings del portal de desarrolladores.

App only solo requiere que envíes un App only Access Token con tu solicitud. Puedes generar un token App only directamente dentro de una App de desarrollador o generarlo usando el endpoint POST oauth2/token.

​

Portal de desarrolladores, Projects y Apps de desarrollador

Para obtener un conjunto de credenciales de autenticación que funcionen con los endpoints de la X API v2, debes registrarte para obtener una cuenta de desarrollador, configurar un Project dentro de esa cuenta y crear una App de desarrollador dentro de ese Project. Luego podrás encontrar tus keys and tokens dentro de tu App de desarrollador.  

​

Límites de tasa

Cada día, muchos miles de desarrolladores realizan solicitudes a la X API. Para ayudar a gestionar el gran volumen de estas solicitudes, se aplican límites de tasa a cada endpoint que restringen la cantidad de solicitudes que puedes hacer en nombre de tu App o en nombre de un usuario autenticado.

Estos endpoints tienen límites de tasa tanto a nivel de App como a nivel de usuario. El límite de tasa de la App significa que tú, como desarrollador, solo puedes realizar una cierta cantidad de solicitudes a este endpoint durante un período de tiempo determinado desde cualquier App (ya sea usando la API Key y la Clave secreta de la API, o el App only Access Token). El límite de tasa de usuario significa que el usuario autenticado en cuyo nombre realizas la solicitud solo puede realizar una búsqueda de List un número determinado de veces en cualquier App de desarrollador.

La tabla a continuación muestra los límites de tasa para cada endpoint.

Endpoint	método HTTP	límite de tasa
/2/lists/:id	GET	75 solicitudes por 15 minutos
/2/users/:id/owned_lists	GET	15 solicitudes por 15 minutos

Fields and expansions

El endpoint GET de X API v2 permite a los usuarios seleccionar exactamente qué data desean obtener de la API utilizando un conjunto de herramientas llamadas fields y expansions. El parámetro expansions te permite expandir objetos referenciados en el payload. Por ejemplo, al buscar una List por ID, puedes obtener las siguientes expansions:

• owner_id

El parámetro fields te permite seleccionar exactamente qué fields dentro de los diferentes objetos de data deseas recibir. Estos endpoints devuelven principalmente objetos List. De forma predeterminada, el objeto List devuelve los fields id y name. Para recibir fields adicionales como list.created_at o list.follower_count, tendrás que solicitarlos específicamente usando el parámetro list.fields.

Hemos añadido una guía sobre cómo usar fields y expansions juntos en nuestro diccionario de datos de X API v2.

La tabla a continuación muestra los fields y expansions disponibles para este grupo de endpoints:

Endpoint	Fields	Expansions
/2/lists/:id	list.fields user.fields	owner_id
/2/users/:id/owned_lists	list.fields user.fields	owner_id

​

Paginación

Consultar las List propiedad del usuario puede devolver una gran cantidad de data. Para garantizar resultados coherentes y de alto rendimiento en todo momento, usamos paginación. La paginación es una función de los endpoints de X API v2 que devuelve más resultados de los que se pueden incluir en una sola respuesta. Cuando eso sucede, la data se devuelve en una serie de “páginas”. Obtén más información sobre cómo paginar resultados.