Guia de integração

Esta página reúne informações sobre várias ferramentas e conceitos essenciais que você deve conhecer ao integrar os endpoints de consulta de List ao seu sistema. Organizamos o conteúdo em algumas seções:

• Ferramentas úteis
• Conceitos principais
• Autenticação
• Portal do desenvolvedor, Projetos e Apps
• Limites de requisições
• fields e expansions
• Paginação

​

Ferramentas úteis

Antes de entrarmos em alguns conceitos fundamentais que ajudarão você a integrar este endpoint, recomendamos que você se familiarize com:

​

Postman

O Postman é uma ótima ferramenta para testar um endpoint. Cada requisição no Postman inclui todos os parâmetros de caminho e de corpo para ajudar você a entender rapidamente o que está disponível. Para saber mais sobre nossas coleções do Postman, visite a página “Usando o Postman”. 

​

Exemplos de código

Quer configurar este endpoint com código na sua linguagem de programação preferida? Temos vários exemplos de código disponíveis que você pode usar como ponto de partida na nossa página do GitHub.

​

Bibliotecas de terceiros

Aproveite uma das bibliotecas de terceiros da nossa comunidade para começar. Você pode encontrar uma biblioteca compatível com os endpoints v2 procurando a tag de versão correspondente.

​

Conceitos-chave

​

Autenticação

Todos os endpoints da X API v2 exigem que você autentique suas solicitações com um conjunto de credenciais, também conhecido como chaves e tokens. Você pode usar Contexto de Usuário do OAuth 1.0a, App only ou OAuth 2.0 Authorization Code com PKCE para autenticar suas solicitações nesses endpoints. 

Contexto de Usuário do OAuth 1.0a, o que significa que você deve usar um conjunto de API Keys e Access Tokens de usuário para fazer uma solicitação bem-sucedida. Os access tokens devem estar associados ao usuário em nome de quem você está fazendo a solicitação. Se você quiser gerar um conjunto de Access Tokens para outro usuário, ele deverá autorizar sua App usando o fluxo OAuth de 3 etapas.

Observe que o OAuth 1.0a pode ser difícil de usar. Se você não estiver familiarizado com esse método de autenticação, recomendamos usar uma biblioteca, uma ferramenta como o Postman ou OAuth 2.0 para autenticar suas solicitações.

OAuth 2.0 Authorization Code com PKCE permite maior controle sobre o escopo de uma aplicação e fluxos de autorização em vários dispositivos. O OAuth 2.0 permite que você selecione escopos específicos e granulares que concedem permissões específicas em nome de um usuário. 

Para habilitar o OAuth 2.0 na sua App, você deve ativá-lo nas configurações de autenticação da sua App, encontradas na seção de configurações da App no portal do desenvolvedor.

App only exige apenas que você envie um App only Access Token com sua solicitação. Você pode gerar um token App only diretamente em uma App de desenvolvedor ou gerar um usando o endpoint POST oauth2/token.

​

Portal do desenvolvedor, Projetos e Apps de desenvolvedor

Para obter um conjunto de credenciais de autenticação que funcione com os endpoints da X API v2, você deve registrar uma conta de desenvolvedor, configurar um Projeto nessa conta e criar um App de desenvolvedor dentro desse Projeto. Em seguida, você poderá encontrar suas chaves e tokens no seu App de desenvolvedor.  

​

Limites de requisições

Todos os dias, muitos milhares de desenvolvedores fazem requisições à X API. Para ajudar a gerenciar o grande volume dessas requisições, limites de requisições são aplicados a cada endpoint, limitando o número de requisições que você pode fazer em nome da sua App ou de um usuário autenticado. 

Esses endpoints são limitados tanto no nível da App quanto no nível do usuário. O limite da App significa que você, desenvolvedor, só pode fazer um certo número de requisições a esse endpoint em um determinado período a partir de qualquer App (considerando o uso da API Key e da Chave secreta da API, ou do App only Access Token). O limite do usuário significa que o usuário autenticado em cujo nome você está fazendo a requisição só pode realizar uma consulta de List um certo número de vezes em qualquer App de desenvolvedor.

A tabela abaixo mostra os limites de requisições para cada endpoint.

Endpoint	método HTTP	limite de taxa
/2/lists/:id	GET	75 requests per 15 minutes
/2/users/:id/owned_lists	GET	15 requests per 15 minutes

Fields and expansions

O endpoint GET da X API v2 permite que os usuários selecionem exatamente quais dados desejam retornar da API usando um conjunto de ferramentas chamadas fields e expansions. O parâmetro expansions permite expandir objetos referenciados no payload. Por exemplo, consultar uma List por ID permite obter as seguintes expansions:

• owner_id

O parâmetro fields permite selecionar exatamente quais fields dentro dos diferentes objetos de dados você deseja receber. Esses endpoints retornam principalmente objetos de List. Por padrão, o objeto List retorna os campos id e name. Para receber campos adicionais, como list.created_at ou list.follower_count, você precisará solicitar especificamente esses campos usando o parâmetro list.fields. 

Adicionamos um guia sobre como usar fields e expansions juntos no nosso X API v2 data dictionary.

 A tabela abaixo mostra os fields e expansions disponíveis 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

​

Paginação

Consultar Lists pertencentes ao usuário pode retornar um volume grande de dados. Para garantir resultados consistentes e de alto desempenho a qualquer momento, usamos paginação. A paginação é um recurso dos endpoints da X API v2 que retornam mais resultados do que cabem em uma única resposta. Quando isso acontece, os dados são retornados em uma série de “páginas”. Saiba mais sobre como paginar os resultados.