API Usando Insomnia

Use Insomnia para solicitações de API
Neste artigo, você aprenderá como configurar o popular cliente Insomnia HTTP para fazer solicitações às APIs RESTful do Brise.

Introdução
Existem inúmeras ferramentas para enviar solicitações HTTP para serviços baseados em REST. Este documento mostrará como usar uma ferramenta popular, o aplicativo Insomnia .

Instalar Insomnia
Obtenha Insomnia. O Insomnia pode ser instalado em sistemas Mac, Linux ou Windows.

Obtenha credenciais de cliente
Para trabalhar com a API do Brise, você precisará de credenciais de cliente para a conta e API que deseja usar. Obtenha suas credenciais de cliente em Token seguindo as instruções de credenciais de autenticação da documentação da API em documentação. Nas etapas abaixo, faremos solicitações de API usando o Insomnia.

Para gerar credenciais de cliente, você deve ter uma conta válida criada através do App Brise para gerar as credenciais para você.

Usando Insomnia
Assim que tiver suas credenciais de cliente, você estará pronto para começar a usar o Insomnia. A Insomnia fará muito trabalho de configuração para você se você importar a especificação OpenAPI para a API, que disponibilizamos para você. As etapas a seguir orientam você na realização de algumas solicitações da API usando o Insomnia .

Configurando uma coleção Insomnia para a API
Obtenha a especificação OpenAPI para a API

Abra a documentação de referência
Clique no botão Download e salve o arquivo brise.openapi.yaml em um local onde você possa encontrá-lo novamente:

Importe a especificação OpenAPI para o Insomnia

Abra o aplicativo Insomnia.
Clique na lista suspensa ao lado de Insomnia e selecione Importar / Exportar:
Em seguida, você será perguntado se deseja importar os dados como uma coleção de solicitação ou um documento de design. Escolha Request Collection:
Você verá uma caixa de diálogo confirmando que os dados foram importados.
Clique em Dashboard no canto superior esquerdo para ver suas Dashboards.Você o verá exibido com o nome apropriado:
Clique na área de trabalho para abri-la.
Você verá uma lista de pastas que contém os vários grupos de solicitações para a API e também um novo ambiente OpenAPI:

Adicionar variáveis ao ambiente
Esta é uma etapa opcional, mas simplificará a configuração da autenticação para solicitações posteriores.

Clique no menu suspenso OpenAPI env e selecione Manage Environments:
Você verá as variáveis de ambiente que o Insomnia criou a partir da especificação OpenAPI na forma de JSON.
Adicione essas variáveis adicionais ao JSON (consulte a documentação):
Ao concluir, clique em Done no canto inferior direito para sair da caixa de diálogo.

Configurar autenticação
Agora estamos prontos para configurar a autenticação para solicitações de API.

Clique na pasta Usuário e selecione Obtém dispositivos.
Clique na guia Auth e no menu suspenso Auth e selecione OAuth 2.0:
Clique na lista suspensa Grant Type e selecione Authorization Code.
No campo URL do token de acesso, comece a digitar "authorization_url" - você verá o menu de preenchimento automático e selecione sua authorization_url variável de ambiente:
Repita a etapa anterior para preencher os campos authorization_url, client_id client_secret com suas variáveis:
Em Advanced Option, no campo credentials selecione In Request Body:
Role para baixo para ver o botão Fetch Tokens e clique nele.
Será aberta uma nova janela para fazer o login com usuário e senha do sistema:

Certifique-se de ver o campo de Tokens de acesso foram preenchido.

● Um dos recursos interessantes do Insomnia é que, uma vez configurado, não é necessário atualizar o token manualmente - o Insomnia obterá novos automaticamente conforme necessário.
● O Insomnia não replica as configurações de autenticação para outras solicitações, portanto, você precisará repetir essas etapas para cada solicitação que deseja testar.
● Um dos recursos interessantes do Insomnia , no entanto, é que, assim que você configurar a autenticação OAuth 2, ele buscará automaticamente novos tokens de acesso conforme necessário. Você não precisa buscar manualmente um novo quando o existente expirar.

Faça uma requisição GET
Agora estamos prontos para fazer uma requisição de obtenção de informações sobre os dispositivos de um usuário.

Como se trata de uma GET, tudo o que você precisa fazer é clicar em Send.
Você deve ver a resposta JSON aparecer na área Resposta:

Envie um pedido de POST
Agora, enviaremos um pedido de POST com alguns dados. Nesse caso, criaremos um novo dispositivo na conta do usuário usando a API. Comece selecionando a solicitação Adiciona dispositivo na pasta Usuário.

Repita todas as etapas na seção Configurar autenticação acima para configurar a autenticação para esta nova solicitação.
Esta solicitação requer um corpo (conteúdo), então clique na guia JSON e insira este um código JSON como o exemplo da imagem do proximo passo para substituir o valor null:
Clique em Send e irá receber a resposta no campo de retorno que pode ser composto do código e em alguns casos um corpo (conteúdo):

Conclusão
Agora você conhece os fundamentos do uso do Insomnia para fazer solicitações às APIs do Brise.