Postman: o que é, testes de API e trabalho com requisições

O que é Postman e principais recursos

Postman é uma plataforma para desenvolver e testar APIs, disponível como aplicativo de desktop (Windows, macOS, Linux) e versão web. Criado originalmente como uma extensão para o Chrome em 2012, o Postman se tornou um ecossistema completo com suporte a monitoramento, mock servers e geração de código de cliente.

Formatos de requisições e respostas

O Postman suporta todos os métodos HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. O corpo da requisição pode estar nos formatos JSON, XML, form-data, x-www-form-urlencoded e binary. A resposta é exibida com destaque de sintaxe, Pretty-print e a possibilidade de visualizar cabeçalhos brutos.

Suporte a autenticação

Os tipos de autenticação integrados incluem Bearer Token, Basic Auth, Digest Auth, OAuth 1.0, OAuth 2.0, API Key e AWS Signature. O Postman adiciona automaticamente os cabeçalhos Authorization de acordo com o tipo selecionado, acelerando o teste de endpoints protegidos sem copiar tokens manualmente.

Interface do Postman e navegação

A interface do Postman consiste em um painel lateral (Collections, APIs, Environments), uma área de trabalho (Request Builder/Response Viewer) e um painel inferior (Console, Runner). A aba Params permite editar os parâmetros de consulta da URL em visualização de tabela, e a aba Headers gerencia os cabeçalhos HTTP.

Postman Console

Console (View → Show Postman Console) registra todas as requisições e respostas de rede em ordem cronológica, incluindo redirecionamentos intermediários e cabeçalhos. É uma ferramenta indispensável ao depurar fluxos OAuth complexos e cadeias de redirecionamentos quando o Response Viewer padrão mostra apenas o resultado final.

Workspaces e trabalho em equipe

O Postman suporta espaços de trabalho em equipe com versionamento de coleções via Fork e Merge. Os membros da equipe podem comentar requisições, propor alterações e sincronizar coleções em tempo real. O Public Workspace permite publicar documentação de API para desenvolvedores externos.

Criação e envio de requisições HTTP

Uma requisição básica no Postman é criada selecionando um método HTTP e inserindo uma URL na barra de endereço. Após o envio, a resposta é exibida no painel inferior com o código de status, tempo de execução e tamanho. Os parâmetros da requisição são codificados automaticamente durante a digitação.

Variáveis dinâmicas e snippets

Variáveis dinâmicas no formato {{$variable}} podem ser usadas na URL e no corpo da requisição. As variáveis integradas {{$guid}}, {{$timestamp}} e {{$randomInt}} geram valores únicos para cada requisição. Os snippets de código estão disponíveis pelo botão Code (), que gera uma requisição equivalente em cURL, Python, JavaScript, Kotlin, Swift e outras linguagens.

// Exemplo de script no Pre-request: geração de assinatura HMAC
const timestamp = Date.now().toString();
const secret = pm.environment.get("api_secret");
const hash = CryptoJS.HmacSHA256(timestamp, secret);
pm.request.headers.add({
    key: "X-Signature",
    value: hash.toString()
});

Coleções e variáveis de ambiente

As coleções são grupos de requisições relacionadas combinadas por projeto ou módulo funcional. Cada coleção pode conter pastas aninhadas, cabeçalhos compartilhados e scripts Pre-request que são executados antes de cada requisição da coleção. A ordem das requisições é definida por arrastar e soltar.

Variáveis de ambiente e variáveis globais

O Postman suporta cinco níveis de variáveis: global, collection, environment, data e local. A prioridade de resolução de conflitos vai do local ao global. Os arquivos de ambiente contêm pares chave-valor para diferentes ambientes: development, staging, production. A troca de ambiente altera todas as URLs e tokens automaticamente.

Automação de testes de API com scripts

Postman permite escrever testes em JavaScript na aba Tests que são executados após o recebimento da resposta. Os testes verificam o código de status, o corpo da resposta, os cabeçalhos e o tempo de execução. Os resultados são exibidos no painel Test Results com indicadores de aprovação coloridos.

Biblioteca pm e encadeamento de requisições

O objeto pm fornece métodos para trabalhar com a resposta: pm.response, pm.expect, pm.variables. O encadeamento de requisições é implementado salvando os dados da resposta de uma requisição em uma variável e usando-os na próxima. Esta é a base para construir testes de integração e verificar a lógica de negócios por meio de uma sequência de chamadas de API.

// Teste: verificação da estrutura da resposta e salvamento do token
pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
});

const json = pm.response.json();
pm.environment.set("auth_token", json.data.token);

Collection Runner e Newman

Collection Runner executa todas as requisições da coleção sequencialmente, executando testes em cada etapa. Newman é a versão de console do Postman para pipelines de CI/CD (Jenkins, GitHub Actions, GitLab CI). O Newman exporta relatórios nos formatos JSON, JUnit e HTML para integração com sistemas de monitoramento.

Trabalho com GraphQL e WebSocket

As requisições GraphQL no Postman são enviadas via POST para um único endpoint com corpo em formato JSON. A aba GraphQL (Beta) fornece um editor visual com destaque de sintaxe, preenchimento automático de campos e schema. As variáveis da requisição são passadas em um painel Variables separado.

Testes de WebSocket e Socket.IO

Postman suporta conexões WebSocket por meio de uma interface separada com painel de mensagens. É possível enviar mensagens de texto e binárias, visualizar o histórico de conexão e reconectar automaticamente em caso de desconexão. O cliente Socket.IO funciona em modo de compatibilidade com o protocolo Engine.IO.

// Teste WebSocket no Postman via API pm
const ws = new WebSocket("wss://echo.websocket.org");
ws.onmessage = (event) => {
    pm.test("Echo response received", () => {
        pm.expect(event.data).to.eql("Hello");
    });
};

Mock servers e monitoramento no Postman

Os mock servers do Postman permitem emular endpoints de API com base em coleções existentes. Isso é útil quando o backend ainda não está pronto, mas o frontend ou o aplicativo móvel já está sendo desenvolvido. Um mock server retorna uma resposta de exemplo da coleção com cabeçalhos e código de status corretos.

Criação de um Mock server

Um mock server é criado a partir da coleção com um clique: selecione a coleção → Mock Servers → Add a new mock server. O Postman gera uma URL única que pode ser usada no código do aplicativo em vez da API real. Para cada requisição da coleção, o mock retorna uma Example Response salva, permitindo testar a interface antes da conclusão do backend.

Monitoramento de API com Postman Monitors

Monitors executam uma coleção em um cronograma (a cada 5 minutos, hora ou dia) e verificam a disponibilidade e a correção da API. Quando um teste falha, o monitor envia uma notificação para e-mail ou Slack. O monitoramento funciona na nuvem do Postman, não requer um servidor separado e suporta até 10.000 requisições por mês no plano gratuito.

// Teste para monitoramento: verificação do tempo de resposta
pm.test("Response time < 2000ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

pm.test("Content-Type is JSON", () => {
    pm.response.to.have.header("Content-Type");
});

Segurança e gerenciamento de segredos

Postman fornece mecanismos para trabalhar com segurança com chaves de API. Variáveis do tipo Secret são criptografadas e não são exibidas na interface. Para trabalho em equipe, use um Workspace com funções Admin, Editor e Viewer.

Criptografia de variáveis

Ao criar uma variável de ambiente, selecione o tipo Secret — o valor é ocultado com asteriscos em todas as interfaces. Os segredos não são exportados para a coleção ao compartilhar e não são exibidos nos logs do Newman. Recomenda-se armazenar senhas e tokens apenas em variáveis Secret.

Integração com Vault

O Postman suporta integração com HashiCorp Vault e AWS Secrets Manager. Scripts Pre-request podem buscar segredos dinamicamente de armazenamento externo, evitando armazenar dados confidenciais nos arquivos de ambiente da coleção.

Segurança e gerenciamento de segredos

Postman fornece mecanismos para trabalhar com segurança com chaves de API. Variáveis do tipo Secret são criptografadas e não são exibidas na interface. Para trabalho em equipe, use um Workspace com funções Admin, Editor e Viewer.

Criptografia de variáveis

Ao criar uma variável de ambiente, selecione o tipo Secret — o valor é ocultado com asteriscos em todas as interfaces. Os segredos não são exportados para a coleção ao compartilhar e não são exibidos nos logs do Newman. Recomenda-se armazenar senhas e tokens apenas em variáveis Secret.

Integração com Vault

O Postman suporta integração com HashiCorp Vault e AWS Secrets Manager. Scripts Pre-request podem buscar segredos dinamicamente de armazenamento externo, evitando armazenar dados confidenciais nos arquivos de ambiente da coleção.