Hoppscotch

Ecossistema de desenvolvimento de API de código aberto e alternativa leve ao Postman para testar APIs REST, GraphQL, WebSocket e em tempo real.

Instalação

Web e Desktop

Comando	Descrição
Navegar para `hoppscotch.io`	Abrir aplicação web Hoppscotch (sem instalação)
Baixar de `hoppscotch.io/download`	Instalar aplicação desktop (macOS, Windows, Linux)
Entrar com GitHub, Google ou email	Criar conta para sincronização de equipe
Opção de instalação PWA do navegador	Instalar como Progressive Web App

Instalação CLI

Comando	Descrição
`npm install -g @hoppscotch/cli`	Instalar CLI globalmente com npm
`npx @hoppscotch/cli`	Executar CLI sem instalar
`hopp --version`	Mostrar versão do CLI
`hopp --help`	Mostrar ajuda do CLI

Instalação Self-Hosted

Comando	Descrição
`docker pull hoppscotch/hoppscotch`	Baixar imagem Docker
`docker compose up -d`	Iniciar instância self-hosted

Docker Compose Self-Hosted

# docker-compose.yml para Hoppscotch self-hosted
version: "3"
services:
  hoppscotch:
    image: hoppscotch/hoppscotch:latest
    ports:
      - "3000:3000"   # Web UI
      - "3100:3100"   # Admin dashboard
      - "3170:3170"   # Backend API
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/hoppscotch
      JWT_SECRET: your-jwt-secret-here
      TOKEN_SALT_COMPLEXITY: 10
      MAGIC_LINK_TOKEN_VALIDITY: 3
      REFRESH_TOKEN_VALIDITY: 604800000
      ACCESS_TOKEN_VALIDITY: 86400000
      VITE_ALLOWED_AUTH_PROVIDERS: GITHUB,GOOGLE,EMAIL
    depends_on:
      - db

  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: hoppscotch

volumes:
  postgres_data:

Requisições HTTP

Fazendo Requisições

Comando	Descrição
Selecionar método (GET, POST, PUT, DELETE, PATCH)	Escolher método HTTP no dropdown
Inserir URL na barra de endereço	Definir endpoint da requisição
Clicar “Send”	Executar a requisição
`Ctrl + Enter`	Enviar requisição (atalho de teclado)
`Ctrl + G`	Enviar e baixar resposta
`Ctrl + K`	Abrir paleta de comandos

Corpo da Requisição

Comando	Descrição
Clicar aba “Body” → selecionar tipo	Definir formato do corpo da requisição
Selecionar “application/json”	Corpo JSON (mais comum)
Selecionar “multipart/form-data”	Upload de arquivos
Selecionar “application/x-www-form-urlencoded”	Dados de formulário
Selecionar “text/plain”	Corpo texto simples
Selecionar “application/xml”	Corpo XML
Selecionar “Binary”	Dados binários brutos

Cabeçalhos e Parâmetros

Comando	Descrição
Clicar aba “Headers” → Adicionar cabeçalho	Adicionar cabeçalhos personalizados
Clicar aba “Parameters”	Adicionar parâmetros de consulta URL
Modo de edição em massa para cabeçalhos	Colar múltiplos cabeçalhos de uma vez
Alternar cabeçalho ativo/inativo	Desativar sem excluir
Usar `<<variable>>` nos valores	Referenciar variáveis de ambiente

Inspeção de Resposta

Comando	Descrição
Ver corpo da resposta	JSON, HTML, XML, binário, imagem
Clicar aba “Headers” na resposta	Inspecionar cabeçalhos da resposta
Código de status e tempo exibidos	Status HTTP, latência, tamanho
Clicar “Copy” na resposta	Copiar resposta para área de transferência
Clicar “Download”	Baixar resposta como arquivo
Resposta JSON auto-formatada	Visualização em árvore retrátil
Clicar “Timeline”	Ver linha do tempo requisição/resposta

Exemplo de Requisição

Method:  POST
URL:     https://api.example.com/users
Headers:
  Content-Type: application/json
  Authorization: Bearer <<auth_token>>

Body (JSON):
{
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin"
}

Response: 201 Created (145ms, 234 B)
{
  "id": 42,
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}

Coleções

Gerenciando Coleções

Comando	Descrição
Clicar ”+” no painel de Coleções	Criar nova coleção
Clicar direito na coleção → “New Request”	Adicionar requisição à coleção
Clicar direito na coleção → “New Folder”	Organizar com subpastas
Arrastar requisições entre pastas	Reordenar itens da coleção
Clicar direito → “Duplicate”	Clonar uma coleção
Clicar direito → “Properties”	Editar configurações da coleção
Clicar direito → “Delete”	Remover coleção
`Ctrl + Shift + P`	Pesquisar dentro de coleções

Importar e Exportar

Comando	Descrição
Clicar “Import” → selecionar arquivo	Importar coleção
Clicar direito → “Export”	Exportar coleção como JSON
Importar de Postman Collection v2	Compatibilidade com Postman
Importar de especificação OpenAPI/Swagger	Gerar requisições automaticamente
Importar de Insomnia	Compatibilidade com Insomnia
Importar de cURL	Colar comando cURL
Importar de HAR	Importar HTTP Archive

Exemplos de Importação

Supported import formats:
  - Hoppscotch Collection (native JSON)
  - Postman Collection v2
  - OpenAPI 3.0 / Swagger 2.0
  - Insomnia v4
  - cURL commands
  - HAR (HTTP Archive)

Import from cURL:
  Paste a cURL command directly into the URL bar
  Hoppscotch auto-parses method, headers, body, and URL

Variáveis de Ambiente

Gerenciando Ambientes

Comando	Descrição
Clicar “Environments” na barra lateral	Abrir gerenciador de ambientes
Clicar ”+” para criar ambiente	Criar novo ambiente
Adicionar pares `key: value`	Definir variáveis
Usar `<<variable_name>>` nas requisições	Referenciar variável em qualquer campo
Selecionar ambiente no dropdown	Ativar um ambiente
Clicar aba “Global”	Definir variáveis globais (sempre ativas)
Clicar direito → “Export”	Exportar ambiente como JSON
Clicar direito → “Duplicate”	Clonar ambiente

Tipos de Variáveis

Tipo	Descrição
Variável regular	Visível na UI, exportada nas coleções
Variável secreta	Mascarada na UI, não exportada
Variável global	Disponível em todos os ambientes
Variável de ambiente	Disponível apenas quando o ambiente está ativo

Exemplo de Ambiente

Environment: "Production"
┌───────────────┬──────────────────────────────┬──────────┐
│ Key           │ Value                        │ Type     │
├───────────────┼──────────────────────────────┼──────────┤
│ base_url      │ https://api.example.com      │ Regular  │
│ api_version   │ v2                           │ Regular  │
│ auth_token    │ eyJhbGciOiJIUzI1NiIsIn...    │ Secret   │
│ timeout       │ 30000                        │ Regular  │
└───────────────┴──────────────────────────────┴──────────┘

Usage in requests:
  URL:    <<base_url>>/<<api_version>>/users
  Header: Authorization: Bearer <<auth_token>>

Autenticação

Tipos de Autenticação

Comando	Descrição
Selecionar “Bearer Token”	Adicionar autenticação Bearer token
Selecionar “Basic Auth”	Autenticação usuário/senha
Selecionar “OAuth 2.0”	Configurar fluxo OAuth 2.0
Selecionar “API Key”	Adicionar API key ao cabeçalho ou parâmetro
Selecionar “AWS Signature”	Autenticação AWS Signature V4
Selecionar “Inherit from parent”	Herdar autenticação da coleção
Selecionar “None”	Remover autenticação
Campos de token suportam `<<variables>>`	Usar variáveis de ambiente em tokens

Configuração OAuth 2.0

OAuth 2.0 Configuration:
  Grant Type:       Authorization Code
  Auth URL:         https://auth.example.com/authorize
  Token URL:        https://auth.example.com/token
  Client ID:        <<client_id>>
  Client Secret:    <<client_secret>>
  Scope:            read write
  Redirect URI:     Auto-configured

Supported grant types:
  - Authorization Code (+ PKCE)
  - Client Credentials
  - Implicit
  - Password Credentials

Testes em Tempo Real

WebSocket

Comando	Descrição
Clicar “Realtime” → “WebSocket”	Abrir cliente WebSocket
Inserir URL `wss://`	Definir endpoint WebSocket
Clicar “Connect”	Estabelecer conexão
Digitar mensagem → clicar “Send”	Enviar mensagem ao servidor
Ver mensagens no painel de log	Monitorar entrada/saída
Clicar “Disconnect”	Fechar conexão
Adicionar protocolos/cabeçalhos	Configurar parâmetros de conexão

Server-Sent Events (SSE)

Comando	Descrição
Clicar “Realtime” → “SSE”	Testar Server-Sent Events
Inserir URL do endpoint SSE	Definir URL do fluxo de eventos
Clicar “Connect”	Começar a receber eventos
Eventos registrados em tempo real	Monitorar fluxo de eventos
Clicar “Disconnect”	Parar de receber

MQTT

Comando	Descrição
Clicar “Realtime” → “MQTT”	Testar conexões MQTT
Inserir URL `mqtt://` ou `wss://`	Definir URL do broker MQTT
Definir Client ID, usuário, senha	Configurar credenciais
Assinar tópicos	Ouvir mensagens
Publicar em tópicos	Enviar mensagens

Socket.IO

Comando	Descrição
Clicar “Realtime” → “Socket.IO”	Testar conexões Socket.IO
Inserir URL do servidor	Definir endpoint Socket.IO
Ouvir eventos	Assinar eventos nomeados
Emitir eventos com dados	Enviar eventos nomeados
Ver status da conexão	Monitorar conexão/desconexão

GraphQL

Testes GraphQL

Comando	Descrição
Clicar aba “GraphQL”	Mudar para modo GraphQL
Inserir URL do endpoint GraphQL	Definir URL do servidor GraphQL
Escrever query no painel editor	Compor consulta GraphQL
Clicar “Schema” para buscar esquema	Carregar esquema do servidor para autocomplete
Adicionar variáveis no painel Variables	Definir variáveis de consulta como JSON
Adicionar cabeçalhos para autenticação	Definir cabeçalhos de autenticação
Clicar “Run” ou `Ctrl + Enter`	Executar consulta
Usar autocomplete do esquema	Obter sugestões de campos

Exemplo GraphQL

Endpoint: https://api.example.com/graphql

Query:
  query GetUsers($limit: Int!) {
    users(limit: $limit) {
      id
      name
      email
      posts {
        title
        createdAt
      }
    }
  }

Variables:
  {
    "limit": 10
  }

Headers:
  Authorization: Bearer <<auth_token>>

Uso do CLI

Executando Coleções

Comando	Descrição
`hopp test collection.json`	Executar testes da coleção
`hopp test collection.json -e environment.json`	Executar com ambiente
`hopp test collection.json --delay 500`	Atraso entre requisições (ms)
`hopp test collection.json --reporter junit`	Saída de relatório de teste JUnit
`hopp test collection.json --reporter json`	Saída de relatório de teste JSON
`hopp test collection.json --bail`	Parar na primeira falha
`hopp test collection.json --env-var KEY=VALUE`	Sobrescrever variável de ambiente

Exemplos CLI

# Run collection with environment
hopp test api-tests.json -e production.json

# Run with delay and stop on failure
hopp test api-tests.json --delay 1000 --bail

# Generate JUnit report for CI/CD
hopp test api-tests.json --reporter junit > results.xml

# Override specific variables
hopp test api-tests.json \
  --env-var "base_url=https://staging.example.com" \
  --env-var "auth_token=test-token-123"

# CI/CD pipeline example
hopp test api-tests.json -e staging.json --bail --reporter junit

Scripts Pré-Requisição e Pós-Requisição

Scripting

Comando	Descrição
Clicar aba “Pre-request”	Adicionar script executado antes da requisição
Clicar aba “Tests”	Adicionar script executado após a resposta
`pw.env.set("key", "value")`	Definir variável de ambiente
`pw.env.get("key")`	Obter variável de ambiente
`pw.expect(response.status).toBe(200)`	Verificar código de status
`pw.expect(response.body).toHaveProperty("id")`	Verificar propriedade do corpo

Exemplos de Scripts de Teste

// Pre-request: Generate timestamp
pw.env.set("timestamp", Date.now().toString());

// Pre-request: Generate random ID
pw.env.set("random_id", Math.random().toString(36).slice(2));

// Test: Check status code
pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

// Test: Check response body
pw.test("Response has user data", () => {
  const body = pw.response.body;
  pw.expect(body).toHaveProperty("id");
  pw.expect(body).toHaveProperty("name");
  pw.expect(body.name).toBe("Alice");
});

// Test: Check response time
pw.test("Response is fast", () => {
  pw.expect(pw.response.status).toBeLessThan(500);
});

// Test: Save token for next request
pw.test("Extract auth token", () => {
  const token = pw.response.body.access_token;
  pw.env.set("auth_token", token);
});

Atalhos de Teclado

Globais

Atalho	Descrição
`Ctrl + Enter`	Enviar requisição
`Ctrl + K`	Paleta de comandos
`Ctrl + S`	Salvar requisição atual
`Ctrl + Shift + P`	Pesquisar coleções
`Ctrl + /`	Alternar barra lateral
`Alt + ↑`	Requisição anterior no histórico
`Alt + ↓`	Próxima requisição no histórico
`F11`	Alternar tela cheia

Equipes e Colaboração

Comando	Descrição
Criar equipe na barra lateral	Configurar espaço de trabalho da equipe
Convidar membros por email	Adicionar colaboradores
Coleções compartilhadas	Bibliotecas de requisições da equipe
Ambientes compartilhados	Conjuntos de variáveis da equipe
Colaboração em tempo real	Ver edições da equipe ao vivo
Controle de acesso baseado em papéis	Papéis de proprietário, editor, visualizador

Boas Práticas

Organizar coleções por domínio de API — Agrupe endpoints relacionados em coleções e use pastas para tipos de recursos (users, orders, products) para manter tudo fácil de encontrar.
Usar ambientes para staging vs produção — Crie ambientes separados para dev, staging e produção com os mesmos nomes de variáveis mas valores diferentes. Troque com um clique.
Armazenar segredos como variáveis secretas — Marque API keys e tokens como tipo “secret” para que fiquem mascarados na UI e excluídos das exportações.
Usar scripts pré-requisição para autenticação — Gere timestamps, calcule assinaturas ou renove tokens automaticamente antes de cada requisição ao invés de copiá-los manualmente.
Escrever testes para endpoints críticos — Adicione scripts de teste para verificar códigos de status, estrutura de resposta e valores chave. Execute via CLI em pipelines CI/CD.
Importar de especificações OpenAPI — Ao trabalhar com APIs documentadas, importe a especificação OpenAPI/Swagger para gerar automaticamente todos os endpoints com parâmetros corretos.
Usar autenticação no nível da coleção — Configure autenticação no nível da coleção e use “Inherit from parent” nas requisições individuais para evitar duplicar a configuração de autenticação.
Exportar coleções para controle de versão — Exporte coleções como JSON e faça commit no repositório para versionamento e compartilhamento com a equipe.
Usar o CLI em CI/CD — Adicione hopp test ao seu pipeline para executar testes de API em cada implantação, garantindo que os endpoints funcionem antes de ir ao ar.
Self-host para APIs sensíveis — Se testando APIs internas ou sensíveis, implante a versão Docker self-hosted para manter todos os dados dentro da sua infraestrutura.