Hoppscotch

Ecosistema open-source per lo sviluppo API e alternativa leggera a Postman per testare API REST, GraphQL, WebSocket e real-time.

Installazione

Web e Desktop

Comando	Descrizione
Naviga su `hoppscotch.io`	Apri l’app web Hoppscotch (nessuna installazione necessaria)
Scarica da `hoppscotch.io/download`	Installa l’app desktop (macOS, Windows, Linux)
Accedi con GitHub, Google o email	Crea account per la sincronizzazione team
Opzione di installazione PWA dal browser	Installa come Progressive Web App

Installazione CLI

Comando	Descrizione
`npm install -g @hoppscotch/cli`	Installa CLI globalmente con npm
`npx @hoppscotch/cli`	Esegui CLI senza installare
`hopp --version`	Mostra la versione CLI
`hopp --help`	Mostra l’aiuto CLI

Installazione Self-Hosted

Comando	Descrizione
`docker pull hoppscotch/hoppscotch`	Scarica l’immagine Docker
`docker compose up -d`	Avvia l’istanza self-hosted

Docker Compose Self-Hosted

# docker-compose.yml per Hoppscotch self-hosted
version: "3"
services:
  hoppscotch:
    image: hoppscotch/hoppscotch:latest
    ports:
      - "3000:3000"   # Interfaccia Web
      - "3100:3100"   # Dashboard amministrativa
      - "3170:3170"   # API Backend
    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:

Richieste HTTP

Effettuare Richieste

Comando	Descrizione
Seleziona metodo (GET, POST, PUT, DELETE, PATCH)	Scegli il metodo HTTP dal menu a tendina
Inserisci URL nella barra degli indirizzi	Imposta l’endpoint della richiesta
Clicca “Send”	Esegui la richiesta
`Ctrl + Enter`	Invia richiesta (scorciatoia da tastiera)
`Ctrl + G`	Invia e scarica la risposta
`Ctrl + K`	Apri la palette dei comandi

Corpo della Richiesta

Comando	Descrizione
Clicca tab “Body” → seleziona tipo	Imposta il formato del corpo della richiesta
Seleziona “application/json”	Corpo JSON (piu comune)
Seleziona “multipart/form-data”	Upload di file
Seleziona “application/x-www-form-urlencoded”	Dati del form
Seleziona “text/plain”	Corpo testo semplice
Seleziona “application/xml”	Corpo XML
Seleziona “Binary”	Dati binari grezzi

Header e Parametri

Comando	Descrizione
Clicca tab “Headers” → Aggiungi header	Aggiungi header personalizzati alla richiesta
Clicca tab “Parameters”	Aggiungi parametri query URL
Modalita modifica massiva per header	Incolla piu header in una volta
Attiva/disattiva header attivo/inattivo	Disabilita senza eliminare
Usa `<<variable>>` nei valori	Riferimento a variabili d’ambiente

Ispezione della Risposta

Comando	Descrizione
Visualizza corpo della risposta	JSON, HTML, XML, binario, immagine
Clicca tab “Headers” sulla risposta	Ispeziona gli header della risposta
Codice di stato e tempo mostrati	Stato HTTP, latenza, dimensione
Clicca “Copy” sulla risposta	Copia la risposta negli appunti
Clicca “Download”	Scarica la risposta come file
Risposta JSON formattata automaticamente	Vista ad albero comprimibile
Clicca “Timeline”	Visualizza la timeline richiesta/risposta

Esempio di Richiesta

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

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

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

Collezioni

Gestione Collezioni

Comando	Descrizione
Clicca ”+” nel pannello Collezioni	Crea nuova collezione
Clic destro collezione → “New Request”	Aggiungi richiesta alla collezione
Clic destro collezione → “New Folder”	Organizza con sotto-cartelle
Trascina richieste tra cartelle	Riordina gli elementi della collezione
Clic destro → “Duplicate”	Clona una collezione
Clic destro → “Properties”	Modifica impostazioni della collezione
Clic destro → “Delete”	Rimuovi collezione
`Ctrl + Shift + P`	Cerca nelle collezioni

Importazione ed Esportazione

Comando	Descrizione
Clicca “Import” → seleziona file	Importa collezione
Clic destro → “Export”	Esporta collezione come JSON
Importa da Postman Collection v2	Compatibilita con Postman
Importa da spec OpenAPI/Swagger	Genera richieste automaticamente
Importa da Insomnia	Compatibilita con Insomnia
Importa da cURL	Incolla comando cURL
Importa da HAR	Importa HTTP Archive

Esempi di Importazione

Formati di importazione supportati:
  - Hoppscotch Collection (JSON nativo)
  - Postman Collection v2
  - OpenAPI 3.0 / Swagger 2.0
  - Insomnia v4
  - Comandi cURL
  - HAR (HTTP Archive)

Importa da cURL:
  Incolla un comando cURL direttamente nella barra URL
  Hoppscotch analizza automaticamente metodo, header, corpo e URL

Variabili d’Ambiente

Gestione Ambienti

Comando	Descrizione
Clicca “Environments” nella barra laterale	Apri il gestore degli ambienti
Clicca ”+” per creare ambiente	Crea nuovo ambiente
Aggiungi coppie `chiave: valore`	Definisci variabili
Usa `<<nome_variabile>>` nelle richieste	Riferimento alla variabile in qualsiasi campo
Seleziona ambiente dal menu a tendina	Attiva un ambiente
Clicca tab “Global”	Imposta variabili globali (sempre attive)
Clic destro → “Export”	Esporta ambiente come JSON
Clic destro → “Duplicate”	Clona ambiente

Tipi di Variabili

Tipo	Descrizione
Variabile regolare	Visibile nell’interfaccia, esportata nelle collezioni
Variabile segreta	Mascherata nell’interfaccia, non esportata
Variabile globale	Disponibile in tutti gli ambienti
Variabile d’ambiente	Disponibile solo quando l’ambiente e attivo

Esempio di Ambiente

Ambiente: "Produzione"
┌───────────────┬──────────────────────────────┬──────────┐
│ Chiave        │ Valore                       │ Tipo     │
├───────────────┼──────────────────────────────┼──────────┤
│ base_url      │ https://api.example.com      │ Regolare │
│ api_version   │ v2                           │ Regolare │
│ auth_token    │ eyJhbGciOiJIUzI1NiIsIn...    │ Segreto  │
│ timeout       │ 30000                        │ Regolare │
└───────────────┴──────────────────────────────┴──────────┘

Utilizzo nelle richieste:
  URL:    <<base_url>>/<<api_version>>/users
  Header: Authorization: Bearer <<auth_token>>

Autenticazione

Tipi di Autenticazione

Comando	Descrizione
Seleziona “Bearer Token”	Aggiungi autenticazione Bearer token
Seleziona “Basic Auth”	Autenticazione username/password
Seleziona “OAuth 2.0”	Configura flusso OAuth 2.0
Seleziona “API Key”	Aggiungi API key a header o parametro query
Seleziona “AWS Signature”	Autenticazione AWS Signature V4
Seleziona “Inherit from parent”	Eredita autenticazione dalla collezione
Seleziona “None”	Rimuovi autenticazione
I campi token supportano `<<variabili>>`	Usa variabili d’ambiente nei token di autenticazione

Configurazione OAuth 2.0

Configurazione OAuth 2.0:
  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:     Configurato automaticamente

Tipi di grant supportati:
  - Authorization Code (+ PKCE)
  - Client Credentials
  - Implicit
  - Password Credentials

Test Real-Time

WebSocket

Comando	Descrizione
Clicca “Realtime” → “WebSocket”	Apri client WebSocket
Inserisci URL `wss://`	Imposta endpoint WebSocket
Clicca “Connect”	Stabilisci connessione
Digita messaggio → clicca “Send”	Invia messaggio al server
Visualizza messaggi nel pannello log	Monitora in entrata/uscita
Clicca “Disconnect”	Chiudi connessione
Aggiungi protocolli/header	Configura parametri di connessione

Server-Sent Events (SSE)

Comando	Descrizione
Clicca “Realtime” → “SSE”	Testa Server-Sent Events
Inserisci URL endpoint SSE	Imposta URL dello stream di eventi
Clicca “Connect”	Inizia a ricevere eventi
Eventi registrati in tempo reale	Monitora lo stream di eventi
Clicca “Disconnect”	Interrompi la ricezione

MQTT

Comando	Descrizione
Clicca “Realtime” → “MQTT”	Testa connessioni MQTT
Inserisci URL `mqtt://` o `wss://`	Imposta URL del broker MQTT
Imposta Client ID, username, password	Configura credenziali
Sottoscrivi ai topic	Ascolta messaggi
Pubblica sui topic	Invia messaggi

Socket.IO

Comando	Descrizione
Clicca “Realtime” → “Socket.IO”	Testa connessioni Socket.IO
Inserisci URL del server	Imposta endpoint Socket.IO
Ascolta su eventi	Sottoscrivi a eventi nominati
Emetti eventi con dati	Invia eventi nominati
Visualizza stato connessione	Monitora connessione/disconnessione

GraphQL

Test GraphQL

Comando	Descrizione
Clicca tab “GraphQL”	Passa alla modalita GraphQL
Inserisci URL endpoint GraphQL	Imposta URL del server GraphQL
Scrivi query nel pannello editor	Componi query GraphQL
Clicca “Schema” per recuperare lo schema	Carica lo schema del server per l’autocompletamento
Aggiungi variabili nel pannello Variabili	Imposta variabili della query come JSON
Aggiungi header per l’autenticazione	Imposta header di autenticazione
Clicca “Run” o `Ctrl + Enter`	Esegui la query
Usa l’autocompletamento dallo schema	Ottieni suggerimenti sui campi

Esempio GraphQL

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

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

Variabili:
  {
    "limit": 10
  }

Header:
  Authorization: Bearer <<auth_token>>

Utilizzo CLI

Esecuzione Collezioni

Comando	Descrizione
`hopp test collection.json`	Esegui test della collezione
`hopp test collection.json -e environment.json`	Esegui con ambiente
`hopp test collection.json --delay 500`	Ritardo tra le richieste (ms)
`hopp test collection.json --reporter junit`	Output report test JUnit
`hopp test collection.json --reporter json`	Output report test JSON
`hopp test collection.json --bail`	Ferma al primo fallimento
`hopp test collection.json --env-var KEY=VALUE`	Sovrascrivi variabile d’ambiente

Esempi CLI

# Esegui collezione con ambiente
hopp test api-tests.json -e production.json

# Esegui con ritardo e ferma al primo fallimento
hopp test api-tests.json --delay 1000 --bail

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

# Sovrascrivi variabili specifiche
hopp test api-tests.json \
  --env-var "base_url=https://staging.example.com" \
  --env-var "auth_token=test-token-123"

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

Script Pre-Request e Post-Request

Scripting

Comando	Descrizione
Clicca tab “Pre-request”	Aggiungi script che viene eseguito prima della richiesta
Clicca tab “Tests”	Aggiungi script che viene eseguito dopo la risposta
`pw.env.set("key", "value")`	Imposta variabile d’ambiente
`pw.env.get("key")`	Ottieni variabile d’ambiente
`pw.expect(response.status).toBe(200)`	Verifica codice di stato
`pw.expect(response.body).toHaveProperty("id")`	Verifica proprieta del corpo

Esempi di Script di Test

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

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

// Test: Controlla codice di stato
pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

// Test: Controlla corpo della risposta
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: Controlla tempo di risposta
pw.test("Response is fast", () => {
  pw.expect(pw.response.status).toBeLessThan(500);
});

// Test: Salva token per la prossima richiesta
pw.test("Extract auth token", () => {
  const token = pw.response.body.access_token;
  pw.env.set("auth_token", token);
});

Scorciatoie da Tastiera

Globali

Scorciatoia	Descrizione
`Ctrl + Enter`	Invia richiesta
`Ctrl + K`	Palette dei comandi
`Ctrl + S`	Salva richiesta corrente
`Ctrl + Shift + P`	Cerca nelle collezioni
`Ctrl + /`	Attiva/disattiva barra laterale
`Alt + ↑`	Richiesta precedente nella cronologia
`Alt + ↓`	Richiesta successiva nella cronologia
`F11`	Attiva/disattiva schermo intero

Team e Collaborazione

Comando	Descrizione
Crea team dalla barra laterale	Configura workspace del team
Invita membri tramite email	Aggiungi collaboratori
Collezioni condivise	Librerie di richieste a livello di team
Ambienti condivisi	Set di variabili a livello di team
Collaborazione in tempo reale	Vedi le modifiche del team in diretta
Accesso basato su ruoli	Ruoli proprietario, editor, visualizzatore

Buone Pratiche

Organizza le collezioni per dominio API — Raggruppa gli endpoint correlati in collezioni e usa cartelle per tipi di risorse (utenti, ordini, prodotti) per mantenere tutto facilmente trovabile.
Usa ambienti per staging vs produzione — Crea ambienti separati per dev, staging e produzione con gli stessi nomi di variabili ma valori diversi. Cambia con un clic.
Salva i segreti come variabili segrete — Contrassegna chiavi API e token come tipo “segreto” cosi sono mascherati nell’interfaccia ed esclusi dalle esportazioni.
Usa script pre-request per l’autenticazione — Genera timestamp, calcola firme o aggiorna token automaticamente prima di ogni richiesta invece di copiarli manualmente.
Scrivi test per gli endpoint critici — Aggiungi script di test per verificare codici di stato, struttura della risposta e valori chiave. Eseguili tramite CLI nelle pipeline CI/CD.
Importa dalle specifiche OpenAPI — Quando lavori con API documentate, importa la specifica OpenAPI/Swagger per generare automaticamente tutti gli endpoint con i parametri corretti.
Usa l’autenticazione a livello di collezione — Imposta l’autenticazione a livello di collezione e usa “Inherit from parent” nelle singole richieste per evitare di duplicare la configurazione di autenticazione.
Esporta le collezioni nel controllo versione — Esporta le collezioni come JSON e fai commit nel tuo repository per il versionamento e la condivisione nel team.
Usa la CLI in CI/CD — Aggiungi hopp test alla tua pipeline per eseguire test API ad ogni deploy, assicurando che gli endpoint funzionino prima di andare in produzione.
Self-host per API sensibili — Se testi API interne o sensibili, distribuisci la versione Docker self-hosted per mantenere tutti i dati all’interno della tua infrastruttura.