Insomnia — cos'è, client REST e GraphQL nello sviluppo

Cos'è Insomnia e le caratteristiche principali

Insomnia è un'applicazione multipiattaforma (Electron) per inviare richieste HTTP e fare debug delle API. È sviluppata dall'azienda Kong dal 2016 come alternativa a Postman con attenzione a velocità e privacy: i dati vengono salvati localmente, la sincronizzazione cloud è opzionale e richiede la registrazione.

Interfaccia e navigazione

La finestra principale è divisa in tre colonne: a sinistra l'albero delle richieste (Workspace), al centro l'editor di richieste con le schede Params, Headers, Body, a destra il pannello di risposta con le modalità Pretty, Raw e Preview. Il tema scuro è attivo per impostazione predefinita e i temi personalizzati sono supportati tramite variabili CSS.

Generazione del codice

Insomnia supporta l'esportazione di una richiesta in codice in più di 20 linguaggi e framework: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP e altri. Il generatore tiene conto di intestazioni, corpo della richiesta e tipo di autenticazione, accelerando l'integrazione dell'API nel codice dell'applicazione.

Insomnia vs Postman: confronto tra client API

Insomnia e Postman risolvono lo stesso compito ma con priorità diverse. Insomnia è più leggero (~80 MB contro ~300 MB), si avvia più velocemente e funziona completamente offline senza imporre la registrazione. Postman offre un ecosistema più maturo con monitoraggio, server mock e workspace di squadra.

Scelta dello strumento in base al compito

Per lo sviluppo individuale e i test rapidi degli endpoint, Insomnia è più comodo grazie alla leggerezza e all'assenza di registrazione. Per il lavoro di squadra con una raccolta condivisa, l'integrazione CI/CD e il monitoraggio delle API di produzione, Postman rimane lo standard del settore.

Organizzazione dell'area di lavoro e degli ambienti

Il workspace in Insomnia contiene un albero di richieste diviso in cartelle. Ogni richiesta può essere di tipo HTTP, GraphQL, WebSocket o gRPC. Sono supportati il trascinamento, la duplicazione e il raggruppamento delle richieste per etichette colorate. Il file di configurazione del workspace viene salvato in formato JSON.

Variabili d'ambiente con ereditarietà

Insomnia supporta ambienti annidati (Sub Environments) che ereditano le variabili del genitore. Ciò consente di definire un URL di base nell'ambiente globale e di sovrascrivere solo i parametri che differiscono per ambienti diversi. Le variabili vengono sostituite tramite la sintassi {`{`}_variable${`}`}.

// Esempio di struttura di un ambiente Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Lavorare con GraphQL in Insomnia

Insomnia offre uno dei migliori editor GraphQL tra i client API. La scheda GraphQL Query consente di scrivere query con autocompletamento dei campi in base allo schema caricato. A destra viene visualizzata la documentazione su tipi, campi e argomenti in tempo reale.

Caricamento dello schema e Introspection

Lo schema viene caricato tramite una richiesta GraphQL Introspection all'endpoint. Insomnia salva lo schema in cache localmente e lo aggiorna automaticamente quando cambia. Dopo il caricamento sono disponibili l'autocompletamento (Ctrl+Spazio), la validazione della richiesta e l'anteprima dei possibili errori prima dell'invio.

# Query GraphQL con variabili in Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Plugin ed estensione delle funzionalità

Insomnia Plugin Hub contiene più di 100 plugin che estendono le funzionalità del client. I plugin si installano tramite il menu Preferences → Plugins o manualmente tramite npm. Le categorie più diffuse includono la generazione di dati di test, l'esportazione in vari formati e i validatori di risposta personalizzati. Ogni plugin è sottoposto a una moderazione obbligatoria prima della pubblicazione nell'hub pubblico degli sviluppatori.

Plugin più diffusi

• insomnia-plugin-faker — generazione di dati fittizi (nome, email, telefono) per le richieste di test.
• insomnia-plugin-aws4 — firma delle richieste con AWS Signature Version 4 per lavorare con Amazon API Gateway e S3.
• insomnia-plugin-utils — utilità per lavorare con date, hashing e codifica Base64 direttamente nelle richieste.

I plugin sono scritti in JavaScript e interagiscono con Insomnia tramite l'API di templating (response.*, request.*, environment.*). Lo sviluppo di un plugin richiede una conoscenza di base di Node.js e la pubblicazione tramite un pacchetto npm con il tag insomnia-plugin.

CLI e automazione dei test

Inso CLI è un'utilità console integrata in Insomnia per eseguire richieste e test dal terminale. Inso esegue richieste singole o intere raccolte, esporta i risultati in JSON e può integrarsi nelle pipeline CI/CD. Il comando inso run collection esegue in sequenza tutte le richieste di una raccolta.

Esempio di integrazione in GitHub Actions

Inso CLI funziona in container Docker e in modalità headless, consentendone l'uso in GitHub Actions e GitLab CI. La configurazione di avvio viene descritta in un file YAML con l'indicazione del percorso della raccolta esportata e dell'ambiente. Sono supportate le asserzioni sul codice di stato e sul corpo della risposta tramite script JavaScript.

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

Integrazione di Insomnia con Git e lavoro di squadra

Insomnia supporta la sincronizzazione delle raccolte tramite Git. I file delle raccolte vengono salvati in formato JSON e possono essere aggiunti al repository del progetto. Insomnia fornisce un client Git integrato per visualizzare le modifiche, creare commit e risolvere i conflitti di merge direttamente dall'interfaccia.

Configurazione della sincronizzazione Git

Per collegare Git, crea una cartella locale con un repository e impostala come directory principale nelle impostazioni di Insomnia. L'applicazione traccia automaticamente le modifiche nei file delle raccolte e le mostra nel pannello Version Control. Sono supportate le operazioni standard: commit, push, pull e visualizzazione del diff tra le versioni.

Lavoro di squadra tramite Insomnia Cloud

Per i progetti senza Git, Insomnia offre la sincronizzazione cloud tramite Insomnia Cloud. Il piano gratuito include fino a 3 membri del team e il backup automatico delle raccolte. I piani a pagamento aggiungono la gestione degli accessi, l'audit delle modifiche e il supporto prioritario.

Design Mode e generazione delle specifiche

Design Mode in Insomnia consente di creare specifiche API in formato OpenAPI 3.0. La modalità funziona come un editor visivo: definisci endpoint e schemi di dati senza scrivere YAML a mano. La specifica può essere esportata in JSON o YAML.

Generazione di una raccolta da OpenAPI

Insomnia importa le specifiche OpenAPI e crea una raccolta di richieste per ogni endpoint. I percorsi e gli schemi vengono convertiti in richieste HTTP pronte. La funzione è utile nell'integrazione con i microservizi, dove la specifica è salvata in un repository separato del team.

Tagging delle richieste

A ogni richiesta può essere assegnata un'etichetta colorata: red, blue, green, orange, purple. Il filtro per tag funziona tramite la barra di ricerca indipendentemente dalla struttura delle cartelle, semplificando la navigazione nei progetti con centinaia di endpoint e molti moduli.

Design Mode e generazione delle specifiche

Design Mode in Insomnia consente di creare specifiche API in formato OpenAPI 3.0 direttamente nell'applicazione. La modalità funziona come un editor visivo: definisci endpoint, schemi di dati e parametri senza scrivere YAML a mano. La specifica può essere esportata in JSON o YAML per la pubblicazione nei repository.

Generazione di una raccolta da OpenAPI

Insomnia importa le specifiche OpenAPI esistenti e crea automaticamente una raccolta di richieste per ogni endpoint. I percorsi e gli schemi vengono convertiti in richieste HTTP pronte con tipi di dati corretti. Questa funzione è utile nell'integrazione con i microservizi, dove la specifica è salvata e mantenuta da un team di sviluppo backend separato.

Tagging e filtro delle richieste

Per organizzare un gran numero di richieste, Insomnia supporta il tagging: a ogni richiesta può essere assegnata un'etichetta colorata: red, blue, green, orange, purple. Il filtro per tag funziona tramite la barra di ricerca indipendentemente dalla struttura delle cartelle, semplificando la navigazione nei progetti con centinaia di endpoint e molti moduli funzionali di API.