Insomnia — o que é, cliente REST e GraphQL no desenvolvimento

O que é o Insomnia e recursos principais

Insomnia é um aplicativo multiplataforma (Electron) para enviar requisições HTTP e depurar APIs. Ele é desenvolvido pela empresa Kong desde 2016 como uma alternativa ao Postman com foco em velocidade e privacidade: os dados são armazenados localmente, a sincronização em nuvem é opcional e exige registro.

Interface e navegação

A janela principal é dividida em três colunas: à esquerda fica a árvore de requisições (Workspace), no centro o editor de requisições com as abas Params, Headers, Body, à direita o painel de resposta com os modos Pretty, Raw e Preview. O tema escuro está ativado por padrão, e temas personalizados são suportados por meio de variáveis CSS.

Geração de código

O Insomnia suporta exportar a requisição para código em mais de 20 linguagens e frameworks: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP e outros. O gerador considera cabeçalhos, corpo da requisição e o tipo de autenticação, o que acelera a integração da API no código da aplicação.

Insomnia vs Postman: comparação de clientes de API

Insomnia e Postman resolvem a mesma tarefa, mas com prioridades diferentes. O Insomnia é mais leve (~80 MB contra ~300 MB), inicia mais rápido e funciona totalmente offline sem impor registro. O Postman oferece um ecossistema mais maduro com monitoramento, servidores mock e workspaces de equipe.

Escolha da ferramenta para a tarefa

Para desenvolvimento individual e testes rápidos de endpoints, o Insomnia é mais conveniente graças à sua leveza e à ausência de registro. Para trabalho em equipe com coleção compartilhada, integração CI/CD e monitoramento de APIs de produção, o Postman continua sendo o padrão da indústria.

Organização do espaço de trabalho e ambientes

O workspace no Insomnia contém uma árvore de requisições dividida em pastas. Cada requisição pode ser do tipo HTTP, GraphQL, WebSocket ou gRPC. São suportados arrastar e soltar, duplicação e agrupamento de requisições por rótulos coloridos. O arquivo de configuração do workspace é armazenado em formato JSON.

Variáveis de ambiente com herança

O Insomnia suporta ambientes aninhados (Sub Environments) que herdam as variáveis do pai. Isso permite definir uma URL base no ambiente global e sobrescrever apenas os parâmetros que diferem para diferentes ambientes. As variáveis são substituídas pela sintaxe {`{`}_variable${`}`}.

// Exemplo da estrutura de um ambiente Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Trabalhando com GraphQL no Insomnia

Insomnia oferece um dos melhores editores de GraphQL entre os clientes de API. A aba GraphQL Query permite escrever consultas com autocompletar de campos com base no esquema carregado. À direita, a documentação sobre tipos, campos e argumentos é exibida em tempo real.

Carregamento do esquema e Introspection

O esquema é carregado por meio de uma requisição GraphQL Introspection ao endpoint. O Insomnia armazena o esquema em cache localmente e o atualiza automaticamente quando ocorrem mudanças. Após o carregamento, ficam disponíveis o autocompletar (Ctrl+Space), a validação da requisição e a prévia de possíveis erros antes do envio.

# Consulta GraphQL com variáveis no Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Plugins e extensão de funcionalidades

Insomnia Plugin Hub contém mais de 100 plugins que ampliam a funcionalidade do cliente. Os plugins são instalados pelo menu Preferences → Plugins ou manualmente via npm. Categorias populares incluem geração de dados de teste, exportação para vários formatos e validadores personalizados de resposta. Cada plugin passa por moderação obrigatória antes de ser publicado no hub público de desenvolvedores.

Plugins populares

• insomnia-plugin-faker — geração de dados falsos (nome, e-mail, telefone) para requisições de teste.
• insomnia-plugin-aws4 — assinatura de requisições com AWS Signature Version 4 para trabalhar com Amazon API Gateway e S3.
• insomnia-plugin-utils — utilitários para trabalhar com datas, hashing e codificação Base64 diretamente nas requisições.

Os plugins são escritos em JavaScript e interagem com o Insomnia por meio da API de templates (response.*, request.*, environment.*). Desenvolver um plugin exige conhecimento básico de Node.js e publicação por meio de um pacote npm com a tag insomnia-plugin.

CLI e automação de testes

Inso CLI é um utilitário de console integrado ao Insomnia para executar requisições e testes a partir do terminal. O Inso executa requisições individuais ou coleções inteiras, exporta os resultados para JSON e pode se integrar a pipelines CI/CD. O comando inso run collection executa sequencialmente todas as requisições de uma coleção.

Exemplo de integração no GitHub Actions

O Inso CLI funciona em contêineres Docker e em modo headless, o que permite usá-lo em GitHub Actions e GitLab CI. A configuração de execução é descrita em um arquivo YAML indicando o caminho para a coleção exportada e o ambiente. São suportadas asserções sobre o código de status e o corpo da resposta por meio de scripts JavaScript.

# Workflow do GitHub Actions com Inso CLI
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

Integração do Insomnia com Git e trabalho em equipe

Insomnia suporta sincronização de coleções via Git. Os arquivos de coleção são armazenados em formato JSON e podem ser adicionados ao repositório do projeto. O Insomnia fornece um cliente Git integrado para visualizar alterações, criar commits e resolver conflitos de merge diretamente da interface.

Configuração da sincronização com Git

Para conectar o Git, crie uma pasta local com um repositório e a defina como diretório raiz nas configurações do Insomnia. O aplicativo rastreia automaticamente as mudanças nos arquivos de coleção e as exibe no painel Version Control. São suportadas operações padrão: commit, push, pull e visualização de diff entre versões.

Trabalho em equipe via Insomnia Cloud

Para projetos sem Git, o Insomnia oferece sincronização em nuvem via Insomnia Cloud. O plano gratuito inclui até 3 membros da equipe e backup automático das coleções. Os planos pagos adicionam gerenciamento de acesso, auditoria de alterações e suporte prioritário.

Design Mode e geração de especificações

Design Mode no Insomnia permite criar especificações de API no formato OpenAPI 3.0. O modo funciona como um editor visual: defina endpoints e esquemas de dados sem escrever YAML manualmente. A especificação pode ser exportada para JSON ou YAML.

Geração de coleção a partir de OpenAPI

O Insomnia importa especificações OpenAPI e cria uma coleção de requisições para cada endpoint. Caminhos e esquemas são convertidos em requisições HTTP prontas. O recurso é útil ao integrar com microsserviços, onde a especificação é armazenada em um repositório separado da equipe.

Marcação de requisições

A cada requisição pode ser atribuído um rótulo colorido: red, blue, green, orange, purple. O filtro por tags funciona pela barra de pesquisa independentemente da estrutura de pastas, o que simplifica a navegação em projetos com centenas de endpoints e muitos módulos.

Design Mode e geração de especificações

Design Mode no Insomnia permite criar especificações de API no formato OpenAPI 3.0 dentro do próprio aplicativo. O modo funciona como um editor visual: defina endpoints, esquemas de dados e parâmetros sem escrever YAML manualmente. A especificação pode ser exportada para JSON ou YAML para publicação em repositórios.

Geração de coleção a partir de OpenAPI

O Insomnia importa especificações OpenAPI existentes e cria automaticamente uma coleção de requisições para cada endpoint. Caminhos e esquemas são convertidos em requisições HTTP prontas com tipos de dados corretos. Este recurso é útil ao integrar com microsserviços, onde a especificação é armazenada e mantida por uma equipe separada de desenvolvimento de backend.

Marcação e filtragem de requisições

Para organizar um grande número de requisições, o Insomnia suporta marcação — a cada requisição pode ser atribuído um rótulo colorido: red, blue, green, orange, purple. O filtro por tags funciona pela barra de pesquisa independentemente da estrutura de pastas, o que simplifica a navegação em projetos com centenas de endpoints e muitos módulos funcionais de API.