Guia de Integração

​

Guia de integração

Esta página contém informações sobre várias ferramentas e conceitos essenciais que você deve conhecer ao integrar os endpoints de membros de List ao seu sistema. Dividimos a página em algumas seções:

• Ferramentas úteis
• Conceitos fundamentais
• 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 essenciais que ajudarão você a integrar este endpoint, recomendamos que você se familiarize com:

​

Postman

O Postman é uma ótima ferramenta que você pode usar para testar um endpoint. Cada solicitação do Postman inclui todos os parâmetros de path e de body para ajudar você a entender rapidamente o que está disponível. Para saber mais sobre nossas coleções do Postman, visite nossa 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 no GitHub.

​

Bibliotecas de terceiros

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

​

Conceitos principais

​

Autenticação

Todos os endpoints da X API v2 exigem que você autentique suas solicitações com um conjunto de credenciais, também conhecidas como chaves e tokens. Você pode usar OAuth 1.0a User Context, OAuth 2.0 Authorization Code com PKCE ou App only para autenticar suas solicitações nos endpoints de lookup de Lists. No entanto, é obrigatório autenticar com OAuth 1.0a User Context ou OAuth 2.0 para os endpoints de manage de Lists.

OAuth 1.0a User Context, o que significa que você deve usar um conjunto de API Keys e Access Tokens de usuário para realizar uma solicitação com êxito. Os access tokens devem estar associados ao usuário em cujo nome 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 optar por OAuth 2.0 ou App only 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 escolher 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, na seção de configurações da App no portal do desenvolvedor.

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

App only requer apenas que você envie um App only Access Token com sua solicitação. Você pode gerar um App only Access Token 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 nesse 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 em nome de um usuário autenticado.

Endpoints de consulta (GET) têm limites tanto no nível da App quanto no nível do usuário; já endpoints de gerenciamento (POST/DELETE) têm limites no nível do usuário. O limite no nível da App significa que você, desenvolvedor, só pode fazer um determinado número de requisições a esse endpoint em um período de tempo definido a partir de qualquer App (pressupondo o uso de API Key e Chave secreta da API, ou do App only Access Token). O limite no nível 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 determinado 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/members	GET	900 requests per 15 minutes
/2/users/:id/list_memberships	GET	75 requests per 15 minutes
/2/lists/:id/members	POST	300 requests per 15 minutes
/2/lists/:id/members/:user_id	DELETE	300 requests per 15 minutes

​

Campos e 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 incluir objetos referenciados no payload. Por exemplo, ao consultar membros de uma List, é possível solicitar as seguintes expansions:

• pinned_tweet_id

O parâmetro fields permite selecionar exatamente quais fields dentro dos diferentes objetos de dados você deseja receber. A consulta de membros de List retorna principalmente objetos de usuário. Por padrão, o objeto de usuário retorna os fields id, name e username. Para receber fields adicionais como user.created_at ou user.description, você precisará solicitar especificamente usando o parâmetro user.fields. 

Adicionamos um guia sobre como usar fields e expansions.

A tabela abaixo mostra os fields e expansions disponíveis para cada endpoint de consulta:

Endpoint	Fields	Expansions
/2/lists/:id/members	user.fields tweet.fields	pinned_tweet_id
/2/users/:id/list_memberships	list.fields user.fields	owner_id

​

Paginação

Consultar membros/associados pode retornar muitos dados. Para garantir resultados consistentes e de alto desempenho a qualquer momento, usamos paginação. A paginação é um recurso em endpoints da X API v2 que retornam mais resultados do que os que podem ser incluídos em uma única resposta. Quando isso acontece, os dados são retornados em uma série de “páginas”. Saiba mais sobre como paginar pelos resultados.