Conhecendo as ferramentas para testes de API REST

Testar APIs REST é uma parte essencial do desenvolvimento de software moderno. Felizmente, existem diversas ferramentas que facilitam esse processo, cada uma com suas características únicas. Este artigo apresenta seis das mais populares: curl, Postman, Insomnia, Bruno, HTTPie e Apidog, incluindo instruções de instalação, uso básico e como adicionar autenticação por token em endpoints que exigem autorização.

curl

Instalação

O curl geralmente vem pré-instalado em sistemas Unix-like (Linux, macOS). No Windows, pode ser instalado via:

• Git Bash
• WSL (Windows Subsystem for Linux)
• Ou baixando o executável oficial em curl.se

Uso Básico

Para fazer uma requisição GET simples:

curl https://api.example.com/users

Com Autenticação (Token Bearer)

Para adicionar um token de autenticação no header Authorization:

curl -H "Authorization: Bearer SEU_TOKEN_AQUI" https://api.example.com/protegido

Substitua SEU_TOKEN_AQUI pelo seu token real. Outros métodos (POST, PUT, etc.) seguem o mesmo padrão, apenas alterando o verb (-X POST, -X PUT, etc.).

Postman

Instalação

Baixe o instalador oficial do site postman.com para Windows, macOS ou Linux. Também está disponível como aplicativo Snap (sudo snap install postman) ou via Homebrew (brew install --cask postman no macOS).

Uso Básico

1. Abra o Postman e clique em "New" → "HTTP Request".
2. Insira a URL (ex: https://api.example.com/users).
3. Selecione o método HTTP (GET, POST, etc.) ao lado da URL.
4. Clique em "Send" para ver a resposta.

Com Autenticação (Token Bearer)

1. Na aba "Headers" da requisição, clique em "Add".
2. Em "Key", digite Authorization.
3. Em "Value", digite Bearer SEU_TOKEN_AQUI.
4. Clique em "Send".

Alternativamente, use variáveis de ambiente para gerenciar tokens de forma mais segura em múltiplas requisições.

Insomnia

Instalação

Disponível para download no site insomnia.rest. Também pode ser instalado via:

• Homebrew: brew install --cask insomnia
• Snap: sudo snap install insomnia
• Chocolatey (Windows): choco install insomnia

Uso Básico

1. Abra o Insomnia e clique em "+" → "New Request".
2. Nomeie a requisição, escolha o método e cole a URL.
3. Clique em "Send".

Com Autenticação (Token Bearer)

1. Na requisição aberta, vá para a aba "Headers".
2. Clique no campo abaixo de "Headers" e selecione "Authorization" no dropdown.
3. No campo de valor, selecione "Bearer Token" e cole seu token.
4. Clique em "Send".

O Insomnia também permite salvar tokens em variáveis de ambiente ou em arquivos de configuração para reutilização.

Apidog

Instalação

Apidog está disponível como aplicativo desktop para Windows, macOS e Linux, além de versão web. Pode ser baixado diretamente do site oficial apidog.com. Também oferece versão para deploy privado para equipes que necessitam de solução on-premise.

Uso Básico

1. Abra o Apidog e clique em "+ New Request" ou use o atalho Ctrl+N.
2. Insira a URL da API (ex: https://api.example.com/users).
3. Selecione o método HTTP desejado (GET, POST, PUT, DELETE, etc.) no dropdown ao lado do campo de URL.
4. Clique no botão "Send" para enviar a requisição e visualizar a resposta.

Com Autenticação (Token Bearer)

1. Na aba "Headers" da requisição, clique no campo abaixo para adicionar um novo header.
2. Em "Key", selecione ou digite Authorization.
3. Em "Value", escolha o tipo "Bearer Token" no dropdown e cole seu token no campo fornecido. Alternativamente, você pode digitar diretamente: Bearer SEU_TOKEN_AQUI.
4. Clique em "Send" para executar a requisição com autenticação.

O Apidog também permite salvar tokens em variáveis de ambiente ou usar seu sistema de gerenciamento de credenciais integrado para maior segurança e reutilização entre diferentes requisições e ambientes.

Bruno

Instalação

O Bruno é uma ferramenta que pode usar pelo terminal e desktop, com o diferencial em versionamento de requisições via Git. Instale-o via:

• npm: npm install -g @usebruno/bruno
• Homebrew: brew install bruno
• Ou baixe o binário diretamente das site oficial da ferramenta useBruno

Uso Básico

1. Inicie uma coleção: bruno init minha-colecao
2. Crie uma nova requisição: bruno request get usuarios (isso cria um arquivo .bru)
3. Edite o arquivo gerado (ex: minha-colecao/usuarios.get.bru) para definir URL, método, etc.
4. Execute: bruno run minha-colecao/usuarios.get.bru

Com Autenticação (Token Bearer)

No arquivo .bru, adicione o header de autorização diretamente:

GET https://api.example.com/protegido
Authorization: Bearer SEU_TOKEN_AQUI

Execute como de costume com bruno run. O Bruno é ideal para equipes que preferem armazenar requisições como código-fonte versionado.

HTTPie

Instalação

Instale via:

• pip: pip install httpie
• Homebrew: brew install httpie
• apt (Ubuntu/Debian): sudo apt install httpie
• Ou veja mais opções em httpie.io/docs#installation

Uso Básico

Para uma requisição GET simples:

http GET https://api.example.com/users

Com Autenticação (Token Bearer)

Adicione o header Authorization diretamente:

http GET https://api.example.com/protegido Authorization:"Bearer SEU_TOKEN_AQUI"

Ou, usando a sintaxe curta para headers:

http GET https://api.example.com/protegido 'Authorization:Bearer SEU_TOKEN_AQUI'

O HTTPie também suporta autenticação via --auth-type e --auth, mas para Bearer Token, definir o header diretamente é o método mais direto.

Considerações Finais

Todas as ferramentas apresentadas cumprem o mesmo propósito fundamental: testar e interagir com APIs REST de forma eficaz. A escolha entre elas depende fortemente de preferências pessoais, contexto de uso e fluxo de trabalho da equipe.

• curl e HTTPie são excelentes para usuários que preferem trabalhar no terminal, especialmente útil para scripts de automação ou ambientes sem interface gráfica.
• Postman, Insomnia, Bruno, Apidog, HTTPie oferecem interfaces gráficas intuitivas, recursos avançados como coleções, variáveis de ambiente, geração de código e testes integrados, sendo ideais para exploratory testing e documentação colaborativa.
• Bruno se destaca por sua abordagem baseada em arquivos, permitindo versionar requisições diretamente no Git, o que é atraente para equipes que adotam práticas de DevOps e Infrastructure as Code.

Não há uma "ferramenta ideal" universal; a melhor escolha é aquela que se alinha melhor com seus hábitos, necessidades específicas e ambiente de trabalho. Experimente algumas delas e adotar aquela que tornar seu processo de teste de API mais eficiente e agradável. Lembre-se: o objetivo é validar suas APIs com confiança, independentemente da ferramenta utilizada.

Boa testagem!

Referências

curl man page

Postman docs

Insomnia

ApiDog

HTTPie Docs

Feito!

Como adicionar o certificado de uma API de terceiros para testar localmente usando o Keytool

Ao integrar uma API de terceiros em um projeto Java, especialmente durante o desenvolvimento local, é comum encontrar erros relacionados a SSL, como:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:
PKIX path building failed: unable to find valid certification path to requested target

Esse erro ocorre quando o certificado da API não é reconhecido pela JVM, geralmente porque é um certificado autoassinado ou emitido por uma autoridade que ainda não está no truststore padrão do Java.

Para resolver isso, é necessário importar o certificado no keystore de confiança da JVM, usando a ferramenta keytool.

O que é o Keytool

O keytool é uma ferramenta de linha de comando que faz parte do JDK.

Ele permite gerenciar keystores (repositórios de certificados e chaves) utilizados pela JVM para autenticação SSL/TLS.

Importante:

O keytool já está disponível nativamente tanto no Linux quanto no Git Bash no Windows (desde que o JDK esteja corretamente instalado e configurado no PATH).

Etapas para importar o certificado no ambiente local

1. Obtenha o certificado da API de terceiros

Você pode exportar o certificado diretamente pelo navegador.

No Google Chrome, por exemplo:

1. Acesse a URL da API (por exemplo: https://api.dominio.com)

2. Clique no cadeado ao lado da barra de endereço

3. Selecione "Detalhes do certificado"

4. Escolha um local para salvar com nome "nome-api-cert.cert" e no tipo selecionar "binário codificado por DER, certificado único" e clica no botão Exportar

2. Localize o cacerts da JVM

O arquivo cacerts é o truststore padrão do Java e fica dentro da pasta lib/security da sua instalação do JDK.

Windows com Git Bash: /c/Program Files/Java/jdk-17/lib/security/cacerts

Linux: /usr/lib/jvm/java-17-openjdk/lib/security/cacerts

Dica: se estiver usando o Git Bash, pode navegar até o diretório do JDK usando comandos Linux normalmente.

3. Execute o comando do Keytool para importar

No terminal (Git Bash ou Linux), rode o seguinte comando:

keytool -importcert -trustcacerts -alias api-terceiro -file /caminho/onde/salvou/nome-api-cert.cert -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit

Explicando os parâmetros:

Parâmetro	Descrição
-importcert	Indica que você quer importar um certificado
-trustcacerts	Confirma que é um certificado confiável
-alias	Nome de identificação do certificado dentro do keystore
-file	Caminho do arquivo .cer que será importado
-keystore	Caminho do keystore onde será armazenado (geralmente cacerts)
-storepass	Senha do keystore (padrão do Java é changeit)

Ao ser questionado se deseja confiar no certificado, digite yes e pressione Enter.

3. Validar se o certificado foi importado corretamente

Após a importação, verifique se o certificado está presente no keystore com:

keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -alias api-terceiro -storepass changeit

Se aparecer o nome do certificado e o emissor (issuer), significa que a importação foi bem-sucedida.

4. Reinicie a aplicação

Depois de importar o certificado, reinicie a aplicação Java ou o servidor (por exemplo, Spring Boot, Quarkus ou Tomcat) para que as alterações entrem em vigor.

Boas práticas

Evite editar diretamente o cacerts da JVM de produção.

O ideal é criar um keystore separado, como custom-truststore.jks, e apontar para ele via propriedades de sistema:

-Djavax.net.ssl.trustStore=/caminho/custom-truststore.jks
-Djavax.net.ssl.trustStorePassword=changeit

Controle de versão:

Nunca coloque certificados ou arquivos .jks diretamente no repositório Git.

Guarde-os em local seguro e documente o procedimento de importação.

Ambiente limpo:

Caso use múltiplas versões do Java, verifique sempre o $JAVA_HOME correto antes de importar o certificado.

Considerações finais

Adicionar o certificado de uma API de terceiros no ambiente local é uma prática comum e necessária quando o SSL não é reconhecido pela JVM.

Usando o keytool, você pode facilmente importar o certificado e eliminar erros de handshake durante o desenvolvimento.

O Git Bash no Windows funciona exatamente como um terminal Linux, e como o keytool é nativo do JDK, o procedimento é o mesmo nos dois sistemas.

Com isso, você garante que sua aplicação consiga se comunicar com segurança com APIs externas, mesmo em ambiente de testes.

Feito!

Utilizando o Faker para criar mocks de API REST

O Faker é uma aplicação de código aberto desenvolvida em Java que ajuda a separar o desenvolvimento frontend do backend, eliminando a necessidade de esperar pelo desenvolvimento da API. Este guia apresenta os passos para criar mocks de API REST usando o Faker e Docker.

Procedimentos:

1. Instalação do Docker:

Certifique-se de ter o Docker instalado em seu sistema para facilitar o uso do Faker.

Caso ainda não tenha o Docker instalado na distro Linux com base Debian, então execute no terminal:

$ sudo apt install docker.io docker-compose

2. Configuração do diretório mocks:

Crie um diretório chamado "mocks" em seu sistema. Dentro deste diretório, crie arquivos JSON para definir os mocks de API.

3. Exemplo de arquivo JSON:

Um exemplo de arquivo JSON para um mock de usuários pode ser assim:

{
  "plugins": [
    {
      "name": "list",
      "args": {
        "count": 5,
        "item": {
          "id": "#random:int:min=1&max=1000#",
          "name": "#random:name#",
          "created_at": "#timestamp#",
          "updated_at": "#timestamp#"
        }
      }
    },
    {"name": "random"},
    {"name": "timestamp"}
  ],
  "request": {
    "method": "GET",
    "path": "/v1/users"
  },
  "response": {
    "body": []
  }
}

Este exemplo define um mock para a rota "/v1/users" que retorna uma lista de 5 usuários com campos como "id", "name", "created_at" e "updated_at" gerados aleatoriamente.

4. Execução do container Docker:

Utilize o seguinte comando Docker para executar o Faker:

docker run --rm -p 3030:3030 -v /diretorio/mocks:/app/mocks dotronglong/faker:stable

Este exemplo define um mock para a rota "/v1/users" que retorna uma lista de 5 usuários com campos como "id", "name", "created_at" e "updated_at" gerados aleatoriamente.

Certifique-se de substituir "/diretorio/mocks" pelo caminho absoluto para o diretório de mocks que você criou anteriormente.

5. Acessando os mocks de API:

Após iniciar o container Docker, você pode acessar os mocks de API através do seguinte endpoint:

curl http://localhost:3030/v1/users

OU no browser http://localhost:3030/v1/users

6. Recursos adicionais:

Para mais informações e recursos sobre o Faker, consulte o repositório oficial no GitHub:

https://github.com/dotronglong/faker

7. Adicionar o Faker Mock no arquivo docker-compose.yml

No diretório, onde estão os arquivos JSON com dados de mock, crie o arquivo

docker-compose.yml, conforme abaixo:

version: '3.8'

services:
  mock_faker:
    image: dotronglong/faker:stable
    container_name: mock_faker
    ports:
      - "3030:3030"
    volumes:
      - ".:/app/mocks"
    restart: unless-stopped

Caso, tenha Faker Mock já está em execução, é necessário finalizar, com docker kill

Depois, execute docker-compose up -d

Adicione a URL do Faker Mock com o endpoint definido no arquivo JSON no Postman com o verbo HTTP (GET ou POST).

Feito!

Sua API é REST? Descubra agora

No mundo do desenvolvimento de software, o termo "API REST" tornou-se um padrão amplamente utilizado para integração entre sistemas. No entanto, nem todas as APIs que se apresentam como RESTful seguem, de fato, os princípios fundamentais do REST. Aderir a esses princípios não é apenas uma questão de semântica, mas também de garantir consistência, escalabilidade e facilidade de uso para os desenvolvedores que consomem sua API.

Neste artigo, exploraremos os elementos essenciais que definem uma API RESTful e apresentaremos um guia prático para ajudar você a verificar se sua API está verdadeiramente alinhada a esse padrão.

Descubra como estruturar endpoints, utilizar métodos HTTP corretamente e aplicar boas práticas que tornam sua API mais eficiente e aderente aos conceitos do REST.

O REST (Representational State Transfer) é um estilo arquitetural que define um conjunto de restrições para a criação de serviços web escaláveis e eficientes. Ele foi introduzido por Roy Fielding em sua tese de doutorado em 2000 e tem se tornado a base para a construção de APIs modernas. Para que uma API seja considerada RESTful, ela deve seguir seis princípios fundamentais:

1. Cliente-Servidor

A arquitetura REST é baseada na separação entre cliente e servidor, o que permite que ambos evoluam de forma independente. O cliente é responsável pela interface do usuário e pela experiência do usuário, enquanto o servidor gerencia o armazenamento e a lógica dos dados. Essa separação melhora a portabilidade do cliente e a escalabilidade do servidor.

2. Stateless (sem estado)

Cada requisição do cliente ao servidor deve conter todas as informações necessárias para que o servidor entenda e processe o pedido. O servidor não deve armazenar informações sobre o estado do cliente entre as requisições. Isso significa que cada chamada é independente, permitindo que as requisições sejam feitas em qualquer ordem.

3. Cacheável

As respostas das APIs REST devem ser rotuladas como cacheáveis ou não, permitindo que os clientes armazenem em cache as respostas para otimizar o desempenho. Isso reduz a necessidade de chamadas repetidas ao servidor para obter os mesmos dados, melhorando a eficiência da comunicação.

4. Interface uniforme

Uma interface uniforme simplifica e desacopla a arquitetura, permitindo que diferentes clientes interajam com o servidor de maneira padronizada. Isso geralmente é implementado através dos métodos HTTP padrão (GET, POST, PUT, DELETE), que definem claramente as operações permitidas em recursos específicos.

5. Sistema em camadas

A arquitetura REST pode ser composta por várias camadas hierárquicas, onde cada camada não conhece as camadas além daquela com a qual está interagindo. Isso permite que intermediários, como proxies e gateways, sejam utilizados para melhorar a segurança e a escalabilidade sem que o cliente precise conhecer a complexidade interna do servidor.

6. Código sob demanda (opcional)

Embora não seja uma exigência, as APIs REST podem permitir que o servidor envie código executável ao cliente quando necessário, estendendo a funcionalidade do cliente sem exigir atualizações constantes.

Diferença entre API REST e RESTful

REST: Conjunto de princípios arquiteturais.

RESTful: Implementação desses princípios em um sistema específico.

Exemplos de endpoints da API de Produtos

• Forma errada de endpoints

A forma incorreta de definir os endpoints para uma API de produtos pode levar a confusões e não seguir as melhores práticas do REST. Aqui estão alguns exemplos de endpoints mal estruturados:

/cadastrarProduto

/editarProduto

/atualizarProduto

/excluirProduto

Esses endpoints não representam recursos, mas sim ações específicas. Isso vai contra o princípio do REST, que enfatiza a manipulação de recursos através de URLs que representam entidades.

• Forma correta de endpoints

A seguir, apresentamos uma forma correta e mais alinhada com os princípios REST para a API de produtos:

1. Criar um Produto

POST /produtos

Sucesso: 201 Created

Erro: 422 Unprocessable Entity

O /produtos representa a coleção de produtos. O método POST é utilizado para criar um novo produto. Caso ocorre algum erro, deve retornar uma mensagem em JSON com código de status 422.

2. Listar todos os produtos

GET /produtos

Permite recuperar uma lista de todos os produtos. Caso, não tiver nenhum produto, deve retornar uma lista vazia.

3. Recuperar um produto específico

GET /produtos/1

Sucesso: 200 OK

Erro: 404 Not Found

Isso é para visualizar um produto específico pela sua identificação (ID). O número 1 representa o ID do produto ou caso o produto não existir deve retornar uma mensagem em JSON com código de status 404.

4. Atualizar um produto existente

PUT /produtos/1

Sucesso: 200 OK

Erro: 404 Not Found

O método PUT é utilizado para atualizar os dados de um produto existente, identificado pelo ID 1 ou caso o produto não existir deve retornar uma mensagem em JSON com código de status 404.

5. Excluir um Produto

DELETE /produtos/1

Sucesso: 200 OK

Erro: 404 Not Found

O método DELETE remove o produto identificado pelo ID 1 ou caso o produto não existir deve retornar uma mensagem em JSON com código de status 404.

Considerações finais

Ao projetar uma API, é fundamental seguir os princípios REST para garantir que os endpoints sejam intuitivos e representem recursos em vez de ações. Isso não apenas melhora a clareza e a usabilidade da API, mas também facilita a manutenção e a escalabilidade no futuro.

Os princípios fundamentais do REST garantem uma comunicação eficiente entre sistemas, promovendo flexibilidade, escalabilidade e interoperabilidade. A adoção dessas diretrizes no desenvolvimento de APIs tem contribuído para o crescimento das aplicações web modernas, especialmente aquelas baseadas em nuvem.

Referência

FIELDING, Roy Thomas. Architectural styles and the design of network-based software architectures. 2000. Dissertação (Doutorado em Ciência da Computação) - University of California, Irvine, 2000. Disponível em: Architectural styles and the design of network-based software architectures . Acesso em: 06/12/2024.

Feito!

Desenvolvendo e testando APIs de loja virtual com ServeRest

Nos últimos anos, com o aumento do comércio eletrônico e das aplicações web, o desenvolvimento de APIs (Interfaces de Programação de Aplicações) tornou-se uma parte essencial do ecossistema digital.

Para garantir que essas APIs funcionem corretamente e atendam às necessidades dos usuários, é fundamental realizar testes eficazes. Uma ferramenta que se destaca nesse cenário é o ServeRest.

O ServeRest é uma biblioteca open-source desenvolvida em Java que facilita o teste de APIs RESTful. O que o torna particularmente interessante é sua capacidade de simular uma loja virtual por meio de endpoints REST, oferecendo um ambiente seguro e controlado para estudos e testes.

Por que Simular uma Loja Virtual?

Simular uma loja virtual por meio de APIs REST é uma prática valiosa por diversos motivos. Primeiramente, ajuda no desenvolvimento e teste de aplicações que dependem dessas APIs, como front-ends de lojas online ou sistemas de gestão de estoque. Além disso, proporciona um ambiente realista para treinamento e aprendizado sobre testes de API, permitindo que estudantes e profissionais pratiquem suas habilidades em um ambiente controlado.

Recursos do ServeRest para Desenvolvimento e Teste

O ServeRest oferece uma série de recursos que o tornam uma ferramenta poderosa para desenvolver e testar APIs de loja virtual:

• Endpoints Simulados: O ServeRest inclui uma variedade de endpoints simulados que representam funcionalidades comuns de uma loja virtual, como gerenciamento de produtos, carrinho de compras, pedidos e usuários.
• Documentação Detalhada: Cada endpoint é acompanhado de uma documentação detalhada que descreve os parâmetros aceitos, os tipos de respostas esperadas e exemplos de uso. Isso facilita o entendimento e o uso das APIs.
• Suporte a Métodos HTTP: O ServeRest suporta uma variedade de métodos HTTP, incluindo GET, POST, PUT e DELETE, permitindo que os usuários realizem operações diversas sobre os recursos da loja virtual.
• Dados de Exemplo: A ferramenta inclui dados de exemplo que podem ser usados para testar diferentes cenários de uso, como adicionar produtos ao carrinho, fazer pedidos e consultar informações de usuários.

Como Começar com ServeRest

Para começar a desenvolver e testar APIs de loja virtual com ServeRest, siga estes passos simples:

Instalação: O ServeRest pode ser baixado diretamente do repositório do GitHub ou incorporado a projetos Maven ou Gradle.

Exploração dos Endpoints: Explore a documentação do ServeRest para entender os diferentes endpoints disponíveis e os tipos de requisições suportadas.

Desenvolvimento e Teste: Use os endpoints simulados para desenvolver e testar as funcionalidades da sua API de loja virtual. Certifique-se de validar as respostas da API em diferentes cenários.

Integração com Ferramentas de Teste: Integre o ServeRest com frameworks de teste populares, como JUnit ou TestNG, para automatizar e escalar seus testes de API.

ServeRest no ambiente Docker

docker run -p 3000:3000 paulogoncalvesbh/serverest:latest

Para visualizar as configurações que são possíveis de serem feitas execute o comando:

docker run -p 3000:3000 paulogoncalvesbh/serverest:latest --help

Teste online

Adicione a URL com os respectivos endpoints (ver a documentação no Swagger do ServerRest) https://serverest.dev/

Considerações finais

O ServeRest é uma ferramenta valiosa para desenvolver e testar APIs de loja virtual. Com sua capacidade de simular endpoints REST de forma fácil e controlada, oferece um ambiente ideal para estudos, treinamento e desenvolvimento de aplicações. Seja você um desenvolvedor em busca de uma ferramenta para testar suas APIs ou um estudante interessado em aprender sobre testes de API, o ServeRest pode ser a solução que você procura.

Experimente o ServeRest hoje mesmo e simplifique seus testes de API de loja virtual!

Referências

https://github.com/ServeRest/ServeRest

Feito!

Conhecendo o Insomnia

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!

Conhecendo o Postman

O que é Postman?

É uma ferramenta de suporte à documentação das requisições feitas pela API REST com os principais métodos HTTP seguintes:

• 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 Postman

Faça o Download do Postman , conforme o SO e arquitetura.

No Windows, basta executar o arquivo executável e seguir os padrões de costume de Windows.

No Linux, extrair o arquivo Postman-linux64-tar.gz, conforme segue:

Extrair o arquivo Postman

$ tar -xzvf Postman-linux64-tar.gz

Acessar o diretório

$ cd Postman

Executar o binário

$ ./Postman

PS: Pode criar um atalho para abrir o Postman no gerenciador gráfico que estiver utilizando na distro também.

Tendo instalado o Postman 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.

Geralmente a API REST tem algum método de autenticação, seja, Basic Auth (autenticação básica), API Key, Bearer Token (JWT), entre outros listados, conforme pode verificar no Postman na aba Authorization em Type.

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 Auth, 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 em 3 pontinhos, 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 aba Body, selecione form-data, preenche os campos Key (nome do campo), Value (o conteúdo correspondente ao campo).

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 aba Body, selecione form-data, preenche os campos Key (nome do campo), Value (o conteúdo correspondente ao campo).

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: DELETE

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 Body 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.

Considerações finais

Nesse post foi apresentado a descrição breve, instalação e modo de utilizar o Postman 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!