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 varias secciones:

• Herramientas útiles
• Conceptos clave
• Autenticación
• Portal de desarrolladores, Proyectos y Apps
• Límites de uso
• Fields y Expansions
• Paginación

​

Herramientas útiles

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

​

Postman

Postman es una excelente herramienta para probar un endpoint. Cada solicitud de Postman incluye todos los parámetros de ruta y de cuerpo para ayudarle a comprender rápidamente qué opciones tiene disponibles. Para obtener más información sobre nuestras colecciones de Postman, visite 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 desarrolladas por nuestra comunidad para empezar. Puedes encontrar una compatible con los endpoints v2 buscando la etiqueta de versión correspondiente.

​

Conceptos clave

​

Autenticación

Todos los endpoints de X API v2 requieren autenticar tus solicitudes con un conjunto de credenciales, también conocidas como keys y tokens. Puedes usar Contexto de usuario de OAuth 1.0a, Solo App 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 Keys y Access Tokens de usuario para realizar una solicitud correctamente. Los access tokens deben estar asociados al usuario en cuyo nombre haces la solicitud. Si deseas generar un conjunto de Access Tokens para otro usuario, ese usuario debe autorizar tu App usando el flujo OAuth de 3 patas.

Ten en cuenta que OAuth 1.0a puede ser difícil de usar. Si no estás familiarizado con este método de Autenticación, te recomendamos usar una biblioteca, 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 alcance (scope) de una aplicación y los flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir ámbitos granulares específicos que te otorgan permisos concretos 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 de configuración de la App del Portal de desarrolladores.

Solo App solo requiere que incluyas un Access Token de Solo App con tu solicitud. Puedes generar un token de Solo App directamente dentro de una App de desarrollador o generar uno usando el endpoint POST oauth2/token.

​

Portal de desarrolladores, Proyectos 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 Proyecto dentro de esa cuenta y crear una App de desarrollador dentro de ese Proyecto. Luego podrás encontrar tus claves y tokens en tu App de desarrollador.  

​

Límites de uso

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 uso a cada endpoint que restringen la cantidad de solicitudes que puedes realizar en nombre de tu App o de un usuario autenticado. 

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

La siguiente tabla muestra los límites de uso para cada endpoint.

Endpoint	Método HTTP	Límite de uso
/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 la X API v2 permite seleccionar exactamente qué data deseas recibir 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, consultar una List por ID te permite 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 entregan principalmente objetos de 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 utilizando el parámetro list.fields. 

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

 La siguiente tabla 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 Listas que pertenecen a un usuario puede devolver una gran cantidad de datos. Para garantizar resultados coherentes y de alto rendimiento en todo momento, usamos la paginación. La paginación es una función de los endpoints de X API v2 que devuelve más resultados de los que pueden incluirse en una sola respuesta. Cuando eso sucede, los datos se devuelven en una serie de “páginas”. Obtén más información sobre cómo paginar los resultados.