Testando APIs Web com o Postman

#PraCegoVer - Transcrição da DevCast

Autor: Olá pessoal, bem-vindos a mais um DevCast. Eu sou o Joel Rodrigues e hoje vamos conhecer o Postman, uma ferramenta bastante útil para testar APIs web ou serviços RESTful.

Ele está disponível na forma de uma aplicação do Chrome ou de uma aplicação para o MacOS. Com ele conseguimos enviar requisições HTTP e analisar seus resultados, efetuar testes em cima dessas requisições para testar nossas APIs web, sejam elas construídas com qualquer linguagem .NET, PHP, Node.js etc.

Uma vez que se elas seguem o serviço RESTFul, esse aspecto não influencia no seu consumo. Vamos enviar apenas requisições HTTP mudando os verbos, por exemplo, GET e o POST, e vamos receber um resultado dela.

Editor: Então essa ferramenta vai nos auxiliar no dia a dia do desenvolvimento dos nossos aplicativos que trabalharem apenas com o REST. Seria isso?

Autor: Exatamente. Tanto para podermos testar as APIs de outros desenvolvedores para saber como consumi-las adequadamente e qual é o seu retorno como também para testar as nossas próprias APIs durante o desenvolvimento para analisar se elas estão funcionando corretamente.

Além disso, podemos utilizar também para testar, por exemplo, nossas APIs quando elas forem publicadas para saber se depois do deploy nenhum comportamento inesperado foi gerado.

Aqui estou utilizando o sistema operacional Windows, então vou optar pela aplicação para o browser Google Chrome.

Basta que eu clique aqui e ele vai abrir a Chrome Web Store, que é a loja de aplicativos do Chrome, e eu posso clicar aqui para adicioná-la no meu browser.

Eu posso confirmar aqui a permissão e quando a instalação for concluída o Postman vai estar disponível lá na página de apps do meu browser.

Finalizada a instalação, ele aparece aqui junto das demais aplicações que eu tenho instalada. Basta que eu clique e ele vai abrir uma nova janela com a interface do Postman. Aqui nessa interface eu posso fazer o login. Caso você prefira, pode optar pelo login com a conta do Google ou pode criar um usuário e senha para se conectar ao Postman.

Esse usuário e senha é importante também para poder compartilhar os recursos com outros desenvolvedores, bem como acessar a sua conta do Postman em vários ambientes. Então se você estiver trabalhando, por exemplo, em dois computadores você pode acessar com a sua conta e os seus recursos e configurações estarão salvas.

Eu já tenho uma conta, então vou fazer o login e essa é a interface principal da ferramenta. Como conseguimos ver aqui, tem diversas opções.

Nós podemos utilizar para otimizar o nosso processo de teste da API fazendo configurações adicionais.

E o ambiente principal aqui é composto por abas, em que vamos ter várias requisições possíveis.

E aqui dentro vamos informar a URL do serviço que estamos testando.

Nesse DevCast vamos utilizar a API de notas ou lembretes disponível na DevMedia, cuja URL conseguimos ver aqui e vai estar disponível aqui na descrição.

E essa API foi desenvolvida com ASP.NET Web API e possui a funcionalidade de listagem e cadastro de lembretes - aqui em inglês notes.

Então precisaremos da URL base dessa API para inserir lá no Postman e fazer os testes [devmedianotesapi.azurewebsites.net]. Aqui podemos ver como a API funciona. Então se enviarmos um GET para o endpoint /API/

Notes ele deve trazer todos os lembretes.

Temos também um GET passando um ID.

PUT, POST e DELETE - esses são os métodos que a nossa API suporta. Então vamos testá-los lá no Postman.

Aqui vou informar o endereço (http://devmedianotesapi.azurewebsites.net/api/notes), lembrando que lá vamos precisar do API/Notes, como vimos na documentação, e vou enviar uma requisição do tipo GET.

Aqui desse lado consigo escolher os vários verbos possíveis do HTTP. Nesse caso eu vou manter o GET, e enviar a minha requisição. Ele vai carregar aqui e vai me trazer o resultado.

Perceba aqui uma listagem dos registros que estão cadastrados lá na base de dados da minha Web API em formato JSON, que é como ela retorna para mim.

Código retornado:

[
{
"id": 164
"Title": "fdsf"
"Body": "sdfs"
},
{
"id": 166
"Title": "Teste"
"Body": "Moises"
},
{
"id": 167
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 168
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 169
"Title": "Do something"
"Body": "Do something at some place"
}
]

Editor: Essa parte de baixo, onde vemos o JSON, não está vinculada com o Postman. Isso aí são os dados realmente enviados da API. Correto Joel?

Autor: Exatamente. Cada API que vamos consumir pode responder de uma forma ou de outra. Neste caso ele retornou uma lista de notes em formato JSON. Então podemos mudar o verbo aqui e enviar uma requisição diferente para aquela nossa API. Por exemplo vamos utilizar um DELETE e para ele aquela API requer que o ID do lembrete que eu quero excluir. Então vou passar, por exemplo, o 164, e ele deve excluir esse ID aqui (http://devmedianotesapi.azurewebsites.net/api/notes/164). Basta que eu envie e ele me retornou um status ok.

Código retornado:

{
"id": 164
"Title": "fdsf"
"Body": "sdfs"
}

Se eu fizer um GET novamente. Agora eu posso fazer, por exemplo, um GET em cima desse ID, que é uma das opções que tem lá, e não vai me retornar nada. Ou seja, aquele registro foi realmente excluído. Se eu fizer um GET novamente na URL base.

Ele não traz mais aquele registro para mim.

Código retornado:

[
{
"id": 166
"Title": "Teste"
"Body": "Moises"
},
{
"id": 167
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 168
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 169
"Title": "Do something"
"Body": "Do something at some place"
}
]

Editor: Joel, notei que você na primeira passou um GET enviou a requisição e depois você foi lá e apagou e mudou o verbo para DELETE e executou novamente. No dia a dia isso fica um pouco... você tem que ficar copiando e colando as tuas URLs. Tem alguma forma de deixarmos, por exemplo sempre num local o nosso GET. Criar uma outra sempre para deletar para facilitar, para não termos que ficar copiando e colando a todo momento. Enfim, perdendo esse tempinho. Existe alguma forma dentro do Postman?

Autor: Existe sim. Podemos criar aqui uma nova aba para uma nova requisição, manter aqui um novo verbo, por exemplo.

Aqui eu vou aproveitar para testar com o POST e a minha requisição com o GET fica aqui mantida. Enquanto nessa outra aba eu vou fazer agora uma requisição, enviando dados para aquela API.

Aqui, para enviar dados, no caso dessa web API ela está pronta para receber dados em formato JSON. Eu posso vir aqui no body, escolher o formato em que eu quero enviar os meus dados, por exemplo, eu poderia enviar como um conjunto de chave e valor, ou como um texto raw, que é o que eu vou escolher aqui e ainda vou mudar o formato para JSON. E aqui eu vou informar o corpo do objeto que eu vou enviar. Vou informar aqui o conteúdo em formato JSON do meu novo registro. Nesse caso eu preciso informar apenas o título e o corpo.

Código enviado:

{
"Title": "Novo lembrete"
"Body": "Assistir DevCast sobre o Postman"
}

Novamente vale destacar que isso aqui vai mudar de cada API. cada uma vai funcionar de uma forma. Vai ter o seu modelo de domínio e os seus objetos, e eu posso clicar em SEND. Novamente ele me trouxe aqui o retorno.

Código retornado:

{
"id": 170
"Title": "Novo lembrete"
"Body": "Assistir DevCast sobre o Postman"
}

Aqui embaixo ele mostra o status da requisição, que foi o 201 created, ou seja, um status padrão do protocolo HTTP.

E aqui embaixo ele traz o ID (170) do meu objeto criado com os seus demais dados.

Código retornado:

[
{
"id": 166
"Title": "Teste"
"Body": "Moises"
},
{
"id": 167
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 168
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 169
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 170
"Title": "Novo lembrete"
"Body": "Assistir DevCast sobre o Postman"
}
]

Editor: Legal. Então agora poderíamos voltar na primeira aba e enviar a requisição novamente, para pegar todos os registros, dessa forma, sem precisar ficar digitando. Não seria isso?

Autor: Exatamente. Se eu vier aqui agora posso simplesmente enviar. Inclusive o meu novo registro já está aqui também.

Código retornado:

[
{
"id": 166
"Title": "Teste"
"Body": "Moises"
},
{
"id": 167
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 168
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 169
"Title": "Do something"
"Body": "Do something at some place"
},
{
"id": 170
"Title": "Novo lembrete"
"Body": "Assistir DevCast sobre o Postman"
}
]

Então com isso podemos criar várias abas e utilizá-las em várias outas URLs para facilitar o desenvolvimento.

Editor: Fica bem legal porque você ganha uma velocidade para isso daí, não é Joel?

Autor: Isso mesmo. E para organizar ainda mais as nossas requisições, uma vez que vamos fazer vários testes de várias URLs, talvez até várias APIs, temos um recurso muito interessante no Postman, que é Collections.

Aqui ele traz uma por padrão. Podemos até excluir e criar as nossas próprias.

Editor: Joel, o que seria uma collection?

Autor: Uma collection é um conjunto de requisições pré-configuradas, inclusive conseguimos colocar uma descrição para elas aqui rapidamente o que é que ela faz, o que é esperado dela, e armazenamos esse conjunto de requisições aqui para que possamos simplesmente acessá-los e testá-los rapidamente sem ter, por exemplo, de informar novamente a URL - sem ter que informar parâmetros ou preencher novamente o corpo.

Também conseguimos compartilhar isso entre membros de um time de desenvolvimento uma vez que estamos logados na nossa conta. E se utilizarmos o Postman em outro computador logado com a nossa conta essa collection também estará disponível. Então poderemos fazer os testes de vários ambientes, basta fazer o login com a conta do Postman.

Editor: Legal. Então conseguimos montar para cada projeto uma coleção de testes. Seria isso?

Autor: Isso mesmo. Vamos ver como funciona isso aqui eu vou criar uma collection, mudar o nome dela para, por exemplo Web API de Lembretes, que é o que essa API faz. Posso dar uma descrição qualquer para ela e vou clicar em Create e dentro dela eu consigo armazenar as minhas requisições.

Editor: Como é que funciona isso?

Autor: Aqui eu tenho a requisição GET já dentro dessa API, que lista todos os lembretes cadastrados. Então posso vir aqui em Save - mandar salvar.

Vou informar qual é o nome dessa requisição, por exemplo, Lista todos, digo o que ele faz (Lista todos os lembretes), assim fica fácil de verificar posteriormente o que essa URL retorna para mim. E posso escolher aqui uma coleção (Web API de Lembretes).

Vou colocar na minha coleção de lembretes que eu acabei de criar. Mando salvar e agora ele já está aqui acessível na minha collection.

Da mesma forma poderia fazer com o POST: novamente clico em salvar e procedo da mesma forma.

Então perceba que eu consigo colocar várias URLs aqui e alternar entre elas. Vou fechar aqui as abas e posteriormente posso vir simplesmente aqui novamente e acessar cada uma delas.

Aqui eu vou seguir com a descrição rápida do que ela faz. Assim eu consigo me orientar rapidamente sobre o que essa URL deve retornar para mim para que eu possa proceder com os testes. Seu eu quiser abrir uma nova aba aqui, por exemplo, posso testar o meu POST. Vou mandar aqui as minhas requisições normalmente e ele me traz o resultado. Aqui eu tenho o POST novamente e posso alternar entre eles livremente.

Aqui na nossa requisição POST é interessante observar outro detalhe bem legal do Postman, uma vez que selecionamos o tipo de dados com o JSON. Ele automaticamente adiciona aqui no Headers da requisição. Essa informação para ser tratada pelo nosso serviço. Perceba que ele adicionou o Header Content-type, informando que ele está enviando uma application/json, que é o formato de dados esperado pela nossa web API.

Uma coisa da qual temos que estar atentos é justamente esse formato dos dados enviados. É importante que o serviço que estamos consumindo esteja pronto para trabalhar com o formato que estamos enviando. Caso contrário, nossa requisição vai gerar um erro e não vai retornar o resultado esperado. Por exemplo, aqui nesse caso o application/json é o formato de dados adequado para a minha API.

Editor: Então, se por exemplo, uma outra API solicitar um texto, não vai poder ficar ali application/json. Não é isso Joel?

Autor: Exatamente. O Postman se encarrega de configurar isso automaticamente à medida que vamos alternando o formato aqui. Por exemplo, aqui temos text/plain, XML etc. Então se selecionarmos aqui text/plain, por exemplo, automaticamente ele muda aqui pra gente.

Outro recurso interessante do Postman é a possibilidade de efetuarmos testes em cima das requisições. Se eu vier aqui no GET, por exemplo, eu posso especificar que o status de retorno dele, ou seja, o status do protocolo do HTTP deve ser o 200, indicando que a requisição foi ok.

Código enviado

tests["status code is 200"] = responseCode === 200;

Quando eu enviar essa requisição ele vai ter aqui uma aba Tests. E aqui eu consigo ver que o meu teste passou, foi bem-sucedido e o retorno foi 200.

Status enviado

Status code is 200

O Postman já traz algumas opções de testes pré-configurados e podemos utilizá-los ou criar os nossos próprios. Eu também posso salvar teste na requisição - basta que eu clique em Save.

Vou adicionar mais um teste aqui, agora no meu POST. Nesse caso do POST, o status deve ser o 201.

Código enviado

tests["status code is 200"] = responseCode === 201;

O código 201 no HTTP indica que um novo recurso foi criado. Vou salvar e aqui na parte superior eu tenho a opção de Runner para executar esses testes de uma só vez. Vou selecionar aqui a minha coleção (Web API de Lembretes) então e posso iniciar os testes. Ele vai executar as minhas requisições. Executar todos os testes me mostra aqui qual foi o resultado e quanto tempo durou a requisição e se o teste passou ou falhou.

Nesse caso, os dois passaram.

Dados enviados

2 passed 0 failed 949 ms
Lista todos - 200 ok - Pass - Status code is 200 - 328 ms
Adicionar lembrete - 201 Created - Pass - Status code is 200 - 621 ms

Ou seja, com isso eu consigo testar rapidamente a minha API saber se ela está se comportando da forma esperada.

Editor: Bacana Joel, mas qual o contexto que utilizamos isso daí se na hora que a requisição é enviada o Postman devolve o status para você?

Autor: Anteriormente estávamos enviando cada requisição individualmente testando cada uma e analisando o seu resultado individualmente. Essa parte de Runner é interessante quando queremos fazer um teste geral da nossa API. Saber se todas as URLs que configuramos estão se comportando da forma esperada. Normalmente as nossas web APIs vão ter várias URLs e cada uma vai responder de uma forma e conseguimos avaliar todas de uma só vez.

Um ponto importante é o tempo de resposta, então aqui podemos observar se o tempo de resposta da nossa API tá muito grande e fazer a análise em cima disso para otimizar essa resposta (328 ms e 621 ms).

Editor: Outra coisa interessante que podemos observar é que caso o desenvolvedor que fez a nossa Web API, se ele modificar alguma URL, alguma coisa podemos identificar o erro direto pelo envio.

Autor: Isso aí. Quando executarmos os testes o resultado vai ser diferente do esperado e podemos perceber rapidamente aqui que alguma coisa mudou e poder sinalizar para o desenvolvedor que aquela URL, por exemplo, não está se comportando como esperado, solicitando assim a sua correção.

Editor: Bacana. Bem interessante o Postman. E é isso aí pessoal, um abraço e até a nossa próxima DevCast.