Pular para o conteúdo principal

​
Consistência nos endpoints da X API v2

Um dos principais aspectos da nova X API v2 é a consistência entre os endpoints. Isso significa que os objetos retornados, os recursos e os comportamentos da API são uniformes em endpoints semelhantes. Você pode esperar que os seguintes elementos sejam os mesmos em todos os endpoints:

​
Nomenclatura de paths

A nomenclatura de paths sempre inclui a versão do endpoint, seguida do recurso. Além disso, o path pode conter um ID relacionado ao recurso anterior, um verbo de seleção que ajuda a determinar quais dados retornar (por exemplo, search ou sample), um verbo de entrega que ajuda a determinar como os dados serão entregues (por exemplo, stream), ou outros recursos que tenham relação com o recurso principal (por exemplo, /user/12/tweets). Por fim, você pode adicionar um parâmetro de query ao final se o endpoint incluir parâmetros de query. Aqui estão alguns exemplos de como esses itens de path e query podem ser organizados: /version/resource/id?param1=value&param2=value /version/resource/delivery/selection?param1=value&param2=value Exemplos de solicitações reais: /2/tweets/1067094924124872705?expansions=attachments.media_keys&tweet.fields=author_id /2/users/2244994945?user.fields=created_at,description /2/tweets/search/stream /2/tweets/search/recent?query=snow

​
JSON Schema

As respostas às requisições são definidas usando JSON Schema. Isso significa que as requisições retornam, de forma consistente, conjuntos de objetos como arrays, com cada elemento tendo um id. As requisições não retornam mapas com ids como chaves.

​
Objeto de resposta e parâmetros

O objeto padrão retornado é o mesmo para cada endpoint desse tipo de objeto:
  • Objetos id são sempre strings.
  • Parâmetros e campos de resposta usam consistentemente a grafia do inglês americano.
  • Os campos ficam vazios ou não são retornados se não houver valor.
  • O objeto entities contém apenas entidades derivadas do texto do Post: isso inclui urls, hashtags, mentions e cashtags.
  • Todas as informações relacionadas a cards, incluindo os campos media_keys e poll_ids, são retornadas no objeto attachments.
Aqui está um exemplo de objeto de resposta do endpoint de consulta de Post individual (com o parâmetro tweet.fields definido como author_id, entities): 
{
   "data": {
       "id": "1278747501642657792",
       "text": "Faz um ano desde que o Twitter Developer Labs foi lançado.\n\nEnquanto construímos a próxima geração da #TwitterAPI (chegando MUITO em breve), veja o que aprendemos e mudamos ao longo do caminho. https://t.co/WvjuEWCa6G",
       "author_id": "2244994945",
       "entities": {
           "urls": [
               {
                   "start": 188,
                   "end": 211,
                   "url": "https://t.co/WvjuEWCa6G",
                   "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html",
                   "display_url": "blog.x.com/developer/en_u…",
                   "images": [
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=orig",
                           "width": 1600,
                           "height": 600
                       },
                       {
                           "url": "https://pbs.twimg.com/news_img/1278747527043362816/7HQRkQeV?format=jpg&name=150x150",
                           "width": 150,
                           "height": 150
                       }
                   ],
                   "status": 200,
                   "title": "Um ano com o Twitter Developer Labs: O que aprendemos e mudamos",
                   "description": "O Labs tem sido inestimável para nos ajudar a entender o que funciona bem e o que não funciona, o que vocês gostaram e o que não gostaram.",
                   "unwound_url": "https://blog.x.com/developer/en_us/topics/tools/2020/a-year-with-twitter-developer-labs.html"
               }
           ],
           "hashtags": [
               {
                   "start": 106,
                   "end": 117,
                   "tag": "TwitterAPI"
               }
           ]
       }
   }
}

​
Autenticação

Todos os endpoints da X API v2 exigem autenticação. Muitos deles aceitam o método OAuth 2.0 Bearer Token, que requer o envio de um Bearer Token na chamada ao endpoint para que a solicitação seja bem-sucedida. Para endpoints que exigem autorização para criar, manipular ou recuperar dados em nome de outro usuário, use o Contexto de Usuário do OAuth 1.0a. Isso significa fornecer as suas chaves e tokens de API da sua App de desenvolvedor, bem como um conjunto de Access Tokens do usuário, que você gera para o usuário em cujo nome está fazendo a solicitação. O fluxo OAuth de 3 etapas pode ajudar você a obter os Access Tokens. Use uma ferramenta ou biblioteca que monte automaticamente esse cabeçalho de autorização. Mais informações sobre autenticação podem ser encontradas em nossa documentação sobre autenticação.

​
Campos

O objeto retornado em cada endpoint é compacto. Para oferecer aos desenvolvedores mais flexibilidade na resposta recebida da API, o parâmetro fields é usado para solicitar os campos desejados. Os campos permanecem consistentes entre endpoints. O Objeto Post retorna os mesmos campos em todos os endpoints em que é retornado. O mesmo conjunto de campos pode ser consultado em endpoints semelhantes. Por exemplo, os mesmos campos de Post podem ser consultados em Posts lookup e para o Post fixado expandido em Users lookup.

​
Expansions

Quando apropriado, expansions estão disponíveis para todos os campos de id aninhados (por exemplo, todos os campos nomeados *_id, como author_id). Expansions também estão disponíveis para todos os campos que possuem um id que não é o identificador de nível superior do objeto atual. Por exemplo, em Posts lookup, o Post é o objeto atual, com o campo id como identificador de nível superior. Os campos author_id ou referenced_tweets.id podem ser expandidos em objetos completos de usuário ou Post adicionando esses valores, separados por vírgula, ao parâmetro expansions. Por favor, relate quaisquer inconsistências que observar relacionadas a esses campos.
⌘I