O que é Insomnia?
É uma ferramenta cliente de API REST, como o Postman, mas tem alguns recursos adicionais, como suporte a GraphQL, gRPC, entre outros.
Os principais métodos HTTP são:
- GET: Utilizado para obter um recurso
- POST: Utilizado para cadastrar uma informação
- PUT: Utilizado para alterar um recurso
- DELETE: Utilizado para deletar um recurso
Instalando o Insomnia
No Linux (Debian, Ubuntu)
Adicionar o repositório no arquivo sources.list.d/insomnia.list
$ echo "deb https://dl.bintray.com/getinsomnia/Insomnia /" | sudo tee -a /etc/apt/sources.list.d/insomnia.list
Adicionar a chave pública
$ wget --quiet -O - https://insomnia.rest/keys/debian-public.key.asc | sudo apt-key add -
Atualizar o repositório e instalar o Insomia pelo gerenciador de pacotes APT
sudo apt update
sudo apt install insomnia
Outras distros, pode instalar via Snap
$ sudo snap install insomnia
Tendo instalado o Insomnia no computador, a URL da API e os endpoints, pode já começar a utilizar a fazer as requisições.
Por convenção de boas práticas, utiliza versionamento na API REST, assim a URL ficaria algo assim https://api.dominio.com/v1/ seguido pelo nome do endpoint.
Ao abrir o Insomnia, tem a opção de criar uma conta e compartilhar dados, mas é opção, pode clicar em Skip.
Feito isso, clique no "+" e "New Request", coloque o nome da requisição que está fazendo na sua API e selecione o método HTTP correspodente, por fim clique em "Create".
Tem a opção de criar um diretório também ao clicar no "+" e "New Folder" e assim organizar as requisições de múltiplas APIs REST por diretórios.
Geralmente a API REST tem algum método de autenticação, seja, Basic (autenticação básica), API Key, Bearer Token (JWT), entre outros listados, conforme pode verificar no Insomnia na aba Auth, ao clicar irá aparecer as opções disponívels de métodos de autenticação.
Após selecionar o método de autenticação utilizado pela API REST, informe o campo correspondente, conforme o método selecionado.
Se selecionar Basic, irá aparecer dois campos Username e Password.
Se selecionar Bearer Token, irá aparecer o campo Token, que corresponde ao JWT.
Assim sucessivamente para outros métodos de autenticação disponíveis.
O próximo é selecionar o método HTTP e a URL da API com o endpoint
Exemplo de requisição GET
URL fictícia: https://api.dominio.com
Endpoint: /produtos
Método HTTP: GET
Se quiser consultar todos os registros de produtos da API do exemplo. Nesse caso, selecione GET, coloque a URL da API com o endpoint produtos e clique no botão "Send", irá obter o resultado. geralmente um JSON como resposta com a listagem de produtos da API.
Caso deseja obter apenas um registro específico, então após o endpoint, adicione o id que é o identificador único.
URL fictícia: https://api.dominio.com
Endpoint: /produtos
identificador único que deseja buscar: 8
Método HTTP: GET
No Postman, a URL ficaria assim https://api.dominio.com/produtos/8
Exemplo de requisição POST
Para facilitar o processo, evitando ter que colocar o método de autenticação da API novamente na próxima requisição, nesse caso POST, passa sobre o mouse no nome da requisição sobre a seta
, vai em Duplicate, assim será duplicado, bastando apenas alterar o método HTTP, nesse caso de GET para POST e apagar o identificador único, colocando a URL real e o endpoint da API.
URL fictícia: https://api.dominio.com
Endpoint: /produtos
Método HTTP: POST
Na primeira aba, clica em cima e selecione "Form" para entrada de campos simples ou "Multipart" para campos texto,numérico ou "JSON" para no formato JSON. Por fim, preenche os campos com o nome do campo e respectivado valor ou se escreve o JSON dos campos de chave e valor.
Faz isso para cada campo, após concluir, clique no botão "Send", que irá obter um retorno em JSON, algo como "Cadastrado com sucesso" e com status 200 ou 201.
Exemplo de requisição PUT
Repita o procedimento explicado anteriormente para duplicar o requição anterior, assim altere o método HTTP de POST para PUT.
URL fictícia: https://api.dominio.com
Endpoint: /produtos
Método HTTP: PUT
Na primeira aba, clica em cima e selecione "Form" para entrada de campos simples ou "Multipart" para campos texto,numérico ou "JSON" para no formato JSON. Por fim, preenche os campos com o nome do campo e respectivado valor ou se escreve o JSON dos campos de chave e valor.
O método PUT é semelhante ao POST, com a diferença que é para atualizar o registro no endpoint, então precisa informar o identificador único para que seja atualizado apenas no id específico.
Informe na URL com o endpoint da API no final o identificador único. A URL ficaria assim https://api.dominio.com/produtos/8. Nesse caso o identificador seria o 8, mas pode ser o que quiser, você escolhe.
Faz isso para cada campo, após concluir, clique no botão "Send", que irá obter um retorno em JSON, algo como "Cadastrado com sucesso" e com status 200 ou 201.
Exemplo de requisição DELETE
Repita o procedimento explicado anteriormente para duplicar o requição anterior, assim altere o método HTTP de PUT para DELETE.
URL fictícia: https://api.dominio.com
Endpoint: /produtos
Método HTTP: PUT
O método DELETE, como o próprio nome já diz, serve para excluir registro no endpoint da API, então precisa informar o identificador único para que seja excluído apenas no id específico.
Informe na URL com o endpoint da API no final o identificador único. A URL ficaria assim https://api.dominio.com/produtos/8. Nesse caso o identificador seria o 8, mas pode ser o que quiser, você escolhe.
Apague o que estiver na aba Form/Multipart/JSON os campos com os valores e clique no botão "Send", irá obter um retorno JSON, que foi excluído com sucesso ou falha, isso se quem o desenvolveu a API adicionou um retorno, geralmente tem, mas em todo caso, tem o status 200.
Bônus
No Insomnia tem o recurso de gerar o código nas linguagens de programação C, C#, Objective-C, Java, Node.js, PHP, Python, Ruby, JavaScript, Kotlin, Shell, PowerShell, Clojure, R. Isso pode ser verificado no nome da requisição que definiu, clica na seta, irá abrir um modal com o campo de seleção das linguagens mencionadas e o cliente cURL, com isso irá gerar o código base funcional.
Considerações finais
Nesse post foi apresentado a descrição breve, instalação e modo de utilizar o Insomnia para utilizar na requisição de API REST de terceiros ou na sua própria que desenvolveu. Para saber mais sobre o status HTTP .
Feito!
