Introdução ao Postman

Neste tutorial, veremos o que é o Postman e como configurá-lo rapidamente.

​

Introdução

O Postman é um aplicativo para desktop e web que permite fazer requisições a uma API por meio de uma interface gráfica. Recomendamos usar o Postman com a X API, a X Ads API e os endpoints do Labs ao explorar a funcionalidade das APIs, bem como ao diagnosticar problemas em sua App.

Atualmente, temos duas coleções do Postman disponíveis:

Coleção X API v2

Coleção X Ads API

​

Pré-requisitos

Antes de começar a usar as coleções do Postman da X, você precisará garantir que tem o acesso e as credenciais adequados para a ferramenta da plataforma de desenvolvedores da X de sua preferência. Você pode saber mais sobre como obter acesso na nossa página “Primeiros passos”.

Depois que você tiver uma conta de desenvolvedor, tiver configurado uma App de desenvolvedor, tiver um conjunto de chaves e tokens de autenticação e tiver configurado corretamente seu ambiente para fazer solicitações à API específica que planeja usar, você pode seguir as etapas abaixo para começar.  

​

Introdução às coleções do Postman da X

​

Etapa um: Adicione uma das coleções do Postman da X à sua conta

Embora você possa configurar manualmente os endpoints específicos que deseja usar no Postman, nós já fizemos o trabalho pesado e criamos uma coleção pronta para uso com as APIs relevantes. Basta clicar em um dos links na seção anterior “Coleções do Postman” e uma coleção com todos os endpoints associados à API selecionada será adicionada ao seu App do Postman. Essas coleções também estão disponíveis na Postman API network. Cada endpoint incluirá automaticamente os parâmetros disponíveis, respostas de exemplo e o tipo de autenticação configurado, de modo que você só precisa adicionar suas credenciais e os valores dos parâmetros para começar a explorar a funcionalidade.

Neste exemplo, vamos trabalhar com a API v2 collection da X.   

​

Etapa dois: Adicione suas chaves e tokens como variáveis de ambiente

Quando você adicionar a coleção à sua instância do Postman, será criado automaticamente um ambiente chamado “X API v2”, no qual você precisará adicionar suas chaves e tokens. Nesta etapa, vamos orientar você no processo de adicionar suas chaves e tokens da sua App de desenvolvedor ao ambiente “X API v2”.

Para adicionar suas chaves e tokens ao ambiente “X API v2”, clique no botão “manage environments” no canto superior direito do Postman. Em seguida, clique no botão de configurações no canto superior direito.

Na lista de ambientes, clique em “X API v2”.

Em seguida, adicione uma variável para cada uma das chaves e tokens que você gerou no painel de Apps, na tabela. Veja um exemplo de como a sua tabela deve ficar:

VARIABLE	INITIAL VALUE	CURRENT VALUE
consumer_key	QAktM6W6DF6F7XXXXXX	QAktM6W6DF6F7XXXXXX
consumer_secret	AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX	AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX
access_token	1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX	1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX
token_secret	rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX	rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX
bearer_token	AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX	AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX

Observe que as chaves e tokens usados na tabela acima são fictícios e não funcionarão se usados em uma requisição.

Depois de adicionar suas credenciais como variáveis e garantir que o ambiente X API v2 esteja selecionado, você estará pronto para fazer requisições à coleção X API v2. Isso porque cada aba de autorização dos endpoints está configurada para herdar automaticamente as variáveis desse ambiente.

Para usar o Postman com Access Tokens de usuário, pule XXXX para conferir detalhes adicionais sobre como fazer isso.

​

Etapa três: selecione um endpoint 

A etapa seguinte é escolher um endpoint da coleção e começar a criar sua solicitação. Você pode selecionar um endpoint na navegação à direita. Veja como isso fica:

Neste exemplo, usaremos o endpoint X API v2 > Post Lookup > Single Post. 

​

Etapa quatro: adicionar valores à guia Params

A próxima etapa é ir até a guia Params. Você verá um conjunto de parâmetros inativos com descrições que explicam a função de cada parâmetro e uma lista de todos os valores possíveis que podem ser enviados na sua solicitação.

Neste exemplo, vamos ativar os parâmetros de consulta expansions e tweet.fields e adicionar os seguintes valores:

Chave	Valor
tweet.fields	created_at,attachments
expansions	author_id

Além de adicionar os parâmetros de consulta, precisamos incluir a Path Variable obrigatória, id. Como este endpoint retorna Posts, precisamos adicionar um ID do Post válido como valor.

Você pode encontrar o ID do Post acessando x.com, clicando em um Post e, em seguida, verificando a URL. Por exemplo, o ID do Post da seguinte URL é 1228393702244134912:

https://x.com/XDevelopers/status/1228393702244134912

Na guia Params, role para baixo além de todos os parâmetros de consulta até a seção “Path Variables”. Adicionaremos o ID do Post que você deseja usar como valor para a chave id.

Se você inseriu tudo desta etapa corretamente, a guia Params deverá se parecer com o seguinte:

​

Etapa cinco: Envie sua solicitação e revise a resposta

Agora que tudo está configurado na sua solicitação, você pode clicar no botão “Send”.

Se tudo estiver configurado corretamente, você deverá receber o seguinte payload:

{
    "data": {
        "author_id": "2244994945",
        "text": "O que o desenvolvedor escreveu no cartão de Dia dos Namorados?\n  \nwhile(true) {\n    I = Love(You);  \n}",
        "id": "1228393702244134912",
        "created_at": "2020-02-14T19:00:55.000Z"
    },
    "includes": {
        "users": [
            {
                "username": "XDevelopers",
                "name": "Desenvolvedores",
                "id": "2244994945"
            }
        ]
    }
}

​

Gerando um Access Token de usuário com o Postman:

​

Usando OAuth 1.0a para gerar um access token de usuário

Confira o processo em três etapas usado na coleção de teste do fluxo OAuth 1.0a.

​

Usando OAuth 2.0 para gerar um access token de usuário

Se você quiser gerar um access token de usuário do OAuth 2.0 no Postman, pode gerar access tokens do OAuth 2.0 para usar em conjunto com a coleção do X API v2 no Postman.

Clique na coleção no seu workspace, vá até a aba “Auth” e selecione o tipo “OAuth 2.0”. Em seguida, sob o título “Configure New Token”, vá em “Configuration Options”. Você pode definir o “Grant Type” como “Authorization Code (With PKCE)”.

Atualize a sua Callback URL para corresponder à callback url associada à sua aplicação. Além disso, atualize os seguintes parâmetros:

• Auth URL - https://x.com/i/oauth2/authorize
• Access Token URL - https://api.x.com/2/oauth2/token
• Client ID - Seu OAuth 2.0 client ID do Dev Portal
• Client Secret - Se você estiver usando um confidential client
• Update Scope - Scopes que correspondam aos endpoints aos quais você deseja se conectar. Exemplo: “tweet.read users.read”
• Sua callback URL (também conhecida como redirect URL). Ela deve corresponder ao que está nas configurações de autenticação da sua App.
• State - state

Quando estiver pronto, clique em “Get New Access Token” para gerar um Access Token. Se aparecer uma caixa de diálogo informando que algo deu errado, talvez seja necessário pressionar o botão Voltar para fazer login. Você precisará autorizar sua App a acessar sua conta clicando em “Authorize app” na caixa de diálogo.

Depois de autorizar sua App, você será direcionado de volta ao Postman, onde poderá ver seu token e selecionar o botão “Use Token” para começar a fazer solicitações em nome de um usuário autorizado.

Agora você está pronto para usar a coleção do Postman.

​

O que vem a seguir

Se você clicar no botão “Code” no Postman, poderá converter a solicitação que acabamos de criar para a linguagem de sua preferência, como Python, Node ou Ruby, para ajudar você a começar. O Postman tem uma excelente documentação que pode ser útil. Também temos alguns exemplos de código no GitHub que podem ajudar você a se integrar aos endpoints mais rapidamente.