Quando estamos desenvolvenvo APIs, a fase de testes é muito importante. Além do teste propriamente dito também é importante que utilizemos um REST Client prático, com boas ferramentas e bem organizado. Por isso hoje eu vou te apresentar o Insomnia, um API Client para suas APIs GraphQL e REST.
Nesse artigo, vamos focar nos testes de API REST, apresentando as principais funcionalidades e como utilizá-las na prática. Para começar, vamos fazer sua instalação.
Instalação
O primeiro passo para a instalação é baixar o Insomnia. Atualmente, há duas vertentes do Insomnia: a Designer e a Core. A que nos interessa nesse artigo é a Core. Você pode encontrar aqui as versões do Core disponíveis de acordo com o seu sistema operacional. Ao entrar na página você verá uma tela parecida com essa:
O processo de instalação no Windows é um wizard super fácil. Basta iniciar o arquivo baixado e confirmar que quer realizar a instalação. É importante mencionar que o Insomnia só está disponível para o Windows 64-bit. Portanto, caso seu Windows seja o de 32-bit, uma boa alternativa para o Insomnia é o Postman, que já explicamos como funciona aqui no blog.
Já no Mac, basta arrastar o arquivo baixado para a sua lista de aplicações. A instalação também pode ser feita por meio do brew, executando o comandobrew cask install insomnia.
No Linux, você pode baixar o instalador e executar o wizard, ou instalar via linha de comando, executando sudo snap install insomnia.
Nesse artigo estou usando a versão 2020.4.2 do Insomnia. Pode ser que você esteja usando alguma outra versão mais nova no momento, o que pode gerar algumas diferenças. Mas não se preocupe, os princípios com certeza serão os mesmos, então você conseguirá aplicar o que será visto sem maiores problemas.
Feita a instalação do Insomnia, vamos começar a configurar nossas requisições!
Primeira impressão
Ao abrir pela primeira vez o Insomnia, você irá se deparar com a seguinte interface:
Como destacado na imagem acima, à esquerda temos a possibilidade de organizar nossas requisições por workspaces. Abaixo, temos uma lista que conterá todas as requisições que adicionarmos.
Você verá que o Insomnia também é uma excelente ferramenta quando se trata de organização, sem deixar a desejar na aparência, pois tem um visual bastante moderno.
API para teste
Vou partir do pressuposto que, durante o artigo, você tem uma API REST disponível para ir realizando os testes. Caso não tenha e sua intenção seja somente aprender a usar o Insomnia, você pode utilizar APIs públicas, como a SWAPI. Os exemplos que serão apresentados aqui é de uma API de pontos turísticos que tenho rodando localmente em minha máquina.
Definindo um Workspace
O primeiro passo é criarmos um workspace para a API específica que iremos trabalhar, para, assim, mantermos tudo bem organizado. Basta clicar no botão azul na interface inicial e selecionar a opção “Create Workspace”, conforme a imagem abaixo:
Em seguida, você deve definir um nome para o novo workspace. No meu caso, irei colocar o nome da minha aplicação, que é Tourist Spots.
Após a criação do workspace, você verá, no botão azul, a indicação de qual está em uso no momento. Veja, no meu aparece aquele que eu acabei de criar:
Agora, para melhorar ainda mais a organização, vamos criar pastas para separar as requisições que iremos criar.
Organizando por pastas
Mesmo que estejamos trabalhando com requisições de uma única aplicação, é comum haver várias entidades diferentes na mesma aplicação. Por exemplo, na minha aplicação, tenho requisições para pontos turísticos, para atrações, para avaliações, para comentários… As pastas, nesse cenário, me ajudam a organizar as requisições pela natureza de cada uma.
A primeira requisição, que irei demonstrar mais à frente, será a de receber todos as atrações turísticas. Vou criar, então, a pasta Atrações. Para isso, basta acionar o atalho Shift + Ctrl + N ou ir na opção New Folder, conforme imagem a seguir:
Você terá que definir um nome para a pasta:
Em seguida, você verá no menu à esquerda a sua pasta recém-criada.
Agora que temos uma pasta para organizarmos as requisições relacionadas às atrações turísticas, vamos adicionar nossa primeira requisição ao Insomnia!
Primeira requisição
A primeira requisição que irei criar é do tipo GET, para receber todas as atrações turísticas, que eu vou chamar de “receber todas”. Para criar uma requisição podemos usar o atalho Ctrl + N ou ir na opção New Request, como na imagem a seguir:
Feito isso, veremos a seguinte tela:
Você pode nomear a nova requisição e definir qual método HTTP essa requisição vai usar. Em seguida, confirme que deseja criá-la.
Perceba que, após adicionarmos a primeira requisição, a interface inicial sofre uma alteração. Agora, a nova requisição aparece no menu à esquerda. O que precisamos fazer nesse momento é selecionar essa requisição e identificar o local em que colocaremos sua URL:
No meu caso, a URL para as atrações turísticas é http://127.0.0.1:8000/attractions, portanto, ficará da seguinte forma:
Após adicionar um endereço de uma API válido, para fazer a requisição, basta ir no botão send. Feito isso a resposta da API será apresentada à direita:
Perceba que é apresentado o status da resposta, o tempo decorrido e seu tamanho.
Esse tipo de informação é muito relevante para certificar-se que sua API realmente está retornando os códigos recomendados na arquitetura REST, além de servir para verificar o desempenho da sua API.
Antes de prosseguirmos para outros tipos de requisições, podemos otimizar um pouco esse processo de criação. Como as requisições que farei de agora em diante terão em comum a URL http://127.0.0.1:8000, vamos armazenar ela numa variável de ambiente do Insomnia. Provavelmente sua aplicação REST também terá uma parte da URL que é comum a todas as requisições.
Variáveis de ambiente do Insomnia
Ter essas variáveis de ambiente traz algumas vantagens, como por exemplo facilidade para fazer alterações em URLs que são muitos referenciadas. Vamos ver isso na prática! No menu abaixo do workspace selecionado, vá na seguinte opção:
Em seguida, você verá a seguinte tela:
Agora, observe que do lado esquerdo tem um item chamado “Base Enviroment”. Ele é, digamos, o ambiente padrão do seu workspace. Você pode, ainda, criar sub-ambientes, para ter uma organização melhor.
Observe que na imagem acima, no meio, tem o objeto JSON, que representa o ambiente escolhido. Perceba que esse objeto está vazio. Vamos adicionar a ele a variável “base_url”, que é a URL comum a todas as requisições que iremos fazer a nossa aplicação REST:
Voltando à requisição Receber todas, na url, em vez de colocar diretamente o endereço base da minha API, preciso colocar somente “base_url”, que é a variável criada. Perceba que irá funcionar normalmente:
Agora, imagine, por exemplo, que eu tenha feito várias requisições com a URL http://127.0.0.1:8000, mas, por algum motivo, a minha aplicação agora está funcionando na URL http://127.0.0.1:8001. Nesse caso, basta ir no menu da variável de ambiente e alterar somente ali. Dessa forma, não preciso ir em todas os locais em que referenciei uma URL base e alterar. Basta alterar na variável!
Uma vez que vimos requisições simples do tipo GET e também como facilitar nossa vida com as variáveis de ambiente, vamos fazer uma requisição em que precisamos enviar algo no corpo dela.
Enviando informação no corpo da requisição
Como o método GET não tem corpo, a próxima requisição será com POST para podermos demonstrar como manipular o corpo da requisição com o Insomnia. Para isso, dentro da pasta Atrações, irei criar uma requisição do tipo POST para criar uma nova atração e, para o tipo de corpo, irei escolher JSON:
Quando criamos uma requisição dessa forma, o cenário será parecido com esse:
Agora, vou preencher a URL e colocar um objeto JSON que representa a nova atração que quero criar:
Feito isso, basta ir em Send para fazer a requisição e recebê-la normalmente. Veja que utilizamos o recurso de variáveis de ambiente. Também é interessante notar que o Insomnia já faz o highlight do JSON para nós, facilitando a visualização dos dados.
No entando, se você for como eu e protegeu seu endpoint com um acesso por autenticação via token, verá, após fazer a requisição, uma mensagem semelhante a essa:
Será apresentado um status de não autorizado e uma mensagem deixando claro que você não forneceu as devidas credenciais. Afinal de contas, onde devemos colocar o token da requisição no Insomnia? Simples! Podemos acrescentá-lo no Header da requisição. Vejamos o meu caso a seguir:
Como é o padrão da minha API, o nome do atributo deve ser Authorization, e o token deve ser antecedido pela palavra Token. Agora, ao fazer a requisição, o resultado esperado ocorre:
Veremos o status de “sucesso” e o objeto que foi criado no meu servidor será retornado.
Uma outra forma de adicionar o token à requisição é por meio da aba Auth. Para isso, primeiro precisamos selecionar o tipo de autenticação que utilizamos na nossa API. Como eu utilizo a do tipo Bearer, irei selecioná-la:
Uma vez selecionada, você verá os campos da autenticação a serem preenchidos:
Perceba que não há mais a necessidade de eu indicar que o atributo é chamado de Authorization, pois nesse tipo de autenticação isso já é padrão. Basta indicar o token e o prefixo que vem antes dele:
Seja passando o token diretamente pelo cabeçalho, seja passando pela aba aba dedicada do Insomnia, você conseguirá adicionar a autenticação nas suas requisições.
É isso, pessoal! O uso dos demais verbos HTTP é muito semelhante ao GET e ao POST. E agora que vimos as principais funcionalidades do Insomnia, é só pôr a mão na massa! Bons estudos a todos!
