Httpie: cos'è, un client HTTP per la riga di comando

Cos'è Httpie e in cosa differisce da cURL

Httpie (o HTTPie) è un'utilità da riga di comando scritta in Python che semplifica l'invio di richieste HTTP rispetto a cURL. La differenza principale è una sintassi vicina al linguaggio naturale: gli argomenti sono separati da spazi, le intestazioni sono indicate con i due punti e i dati JSON con un segno di uguale senza eseguire l'escape delle virgolette.

Confronto tra cURL e Httpie

La stessa richiesta POST in cURL richiede almeno tre flag (-X, -H, -d) e l'escape manuale del JSON. Httpie fa lo stesso con tre parole e senza flag, impostando automaticamente Content-Type: application/json ed evidenziando l'output. La risposta viene formattata con rientri ed evidenziazione della sintassi per impostazione predefinita.

Sintassi delle richieste in Httpie

Httpie usa un formato di riga di comando unico senza flag per i parametri principali. Il metodo HTTP è specificato come primo argomento (GET, POST, PUT, DELETE, PATCH), l'URL come secondo. Se il metodo viene omesso, Httpie sceglie automaticamente GET (per le richieste senza corpo) o POST (con corpo).

Tipi di argomenti

• Header:Value — intestazioni della richiesta con i due punti, senza spazio dopo i due punti: Authorization:"Bearer token".
• key=value — campi dell'oggetto JSON nel corpo della richiesta: name=John age=30.
• key:=value — valori JSON non stringa (numeri, booleani, array): active:=true tags:=["dev","test"].
• key@file — caricamento di un valore da un file: avatar@~/photo.jpg.

Httpie determina automaticamente il tipo di dato: se viene passato key=value, il corpo viene inviato come JSON. Se viene passato testo grezzo tramite --raw, viene inviato come testo semplice. Il formato form-data viene attivato con il flag -f.

# Richiesta POST con dati JSON e un'intestazione
http POST https://api.example.com/users \
    name="John Doe" \
    email="john@example.com" \
    role:="admin" \
    Authorization:"Bearer test123"

# Risposta con evidenziazione e Pretty-print
HTTP/1.1 201 Created
Content-Type: application/json
{
    "id": 42,
    "name": "John Doe"
}

Lavorare con JSON e file

La serializzazione JSON in Httpie funziona automaticamente: un valore passato come key=value diventa un campo stringa del JSON. Per numeri e valori booleani si usa key:=value. Gli oggetti annidati vengono creati con la notazione a punti: address.city=Moscow.

Caricamento di file e dati binari

Httpie supporta il formato multipart/form-data per caricare file e dati tramite la sintassi key@path. Se è necessario inviare il contenuto di un file come corpo grezzo della richiesta, si usa il reindirizzamento dell'input: http POST example.com < file.json. Per scaricare la risposta in un file si usa il flag -d (download).

# Invio di JSON da un file
http POST https://api.example.com/users < user.json

# Caricamento di un file tramite multipart
http -f POST https://api.example.com/upload \
    photo@~/photo.jpg \
    description="Profile photo"

Gestione di sessioni e cookie

Le sessioni in Httpie preservano lo stato tra le richieste: cookie, intestazioni e parametri di autenticazione. Una sessione viene creata con il flag --session=name. I dati della sessione vengono memorizzati in un file JSON nella cartella ~/.httpie/sessions/. Una sessione con il suffisso :readonly non viene aggiornata dopo una richiesta.

Esempio di test con sessione

Innanzitutto, viene inviata una richiesta POST a /auth/login con le credenziali — il server restituisce un cookie di sessione. Tutte le richieste successive a endpoint protetti all'interno della stessa sessione inviano automaticamente il cookie salvato, simulando il comportamento del browser durante il test dell'API di un'app mobile.

# Passaggio 1: autenticazione
http --session=app-test POST https://api.example.com/auth/login \
    username="dev" password="secret"

# Passaggio 2: richiesta con il cookie di sessione salvato
http --session=app-test GET https://api.example.com/users/me

Autenticazione e intestazioni

Httpie supporta tutti i principali tipi di autenticazione tramite flag: -a user:pass per Basic Auth, --auth-type=digest per Digest, --auth-type=bearer TOKEN per Bearer Token. Le intestazioni personalizzate vengono aggiunte come HeaderName:value in qualsiasi punto del comando.

OAuth 2.0 e Bearer Token

Per testare un'API con OAuth 2.0, il token viene passato tramite l'intestazione Authorization. Httpie non gestisce il ciclo di vita del token a livello di kernel — lo fa uno script esterno. Il comando http --auth-type=bearer --auth="$TOKEN" GET https://api.example.com/resource equivale a specificare esplicitamente l'intestazione con il token.

Uso di Httpie negli script CI/CD

Httpie è ideale per le pipeline CI/CD grazie a zero dipendenze (tranne Python) e output leggibile. I comandi sono facili da leggere nei log senza parsing aggiuntivo. Lo strumento viene installato tramite pip ed è disponibile in tutte le immagini Docker più diffuse, inclusi Alpine, Ubuntu e le immagini CI ufficiali di Jenkins e GitLab. Questo rende Httpie una scelta comoda per il test automatizzato di API REST e microservizi.

Verifica dell'endpoint health nel deploy

Uno scenario tipico è verificare lo stato dell'API dopo il deploy di un'applicazione. Httpie invia una richiesta all'endpoint health e termina con un codice diverso da zero se la risposta non corrisponde a quella prevista. Il flag --check-status restituisce automaticamente un errore per i codici di stato >= 300.

# Health check nello script di deploy
http --check-status GET https://api.staging.example.com/health
    status:="ok" && \
    echo "L'API è sana" || \
    echo "Il controllo dell'API è fallito"

Funzionalità avanzate e plugin di Httpie

Httpie supporta i plugin tramite il sistema Package Index. I plugin aggiungono nuovi tipi di autenticazione, formati di serializzazione e trasporti. L'installazione avviene tramite pip: pip install httpie-plugin-name. Dopo l'installazione, il plugin viene attivato automaticamente al successivo avvio di Httpie.

Plugin Httpie più diffusi

• httpie-jwt-auth — ottenimento e rinnovo automatici dei token JWT tramite il meccanismo di refresh token.
• httpie-oauth — supporto di OAuth 2.0 Client Credentials e flusso Authorization Code con scambio automatico del codice con un token.
• httpie-editor — apre il corpo della richiesta in un editor di testo (vim, nano, VS Code) prima dell'invio.
• httpie-image — mostra le immagini della risposta direttamente nel terminale (richiede kitty o iTerm2).

Scripting e parsing dell'output

Httpie supporta il filtraggio simile a jq tramite l'opzione --pretty=format e l'output compatibile con cURL tramite --print. Il flag --quiet disattiva l'output colorato per una migliore leggibilità nei log CI. Per l'elaborazione programmatica della risposta, usa il flag --body, che produce solo il corpo della risposta senza intestazioni.

# Estrazione di un campo da una risposta JSON con jq
http GET https://api.example.com/users/1 | jq '.name'

# Output solo del corpo della risposta (senza intestazioni)
http --body GET https://api.example.com/health

# Invio in batch con dati diversi da un file
while read -r line; do
    http POST https://api.example.com/items $line
done < items.txt

Formati di output e personalizzazione

Httpie supporta i formati di output tramite il flag --print: H (intestazioni della richiesta), B (corpo della richiesta), h (intestazioni della risposta), b (corpo della risposta). La combinazione --print=hb produce solo intestazioni e corpo della risposta. Il flag --pretty=all attiva la formattazione a colori con rientri.

Schemi di colori personalizzati

Httpie supporta la personalizzazione tramite la variabile HTTPIE_COLORS. Configura i colori per URL, intestazioni, JSON e codici di stato. Sono disponibili temi integrati: autumn, borland, fruity, monokai, native, tango per diversi terminali.

Output in formato JSON

Per l'elaborazione programmatica, usa --body --pretty=none, che restituisce JSON grezzo. L'output compatto è utile per passarlo a jq, sed e altri parser durante l'automazione dei test API negli script.

Formati di output e personalizzazione dell'aspetto

Httpie supporta diversi formati di output tramite il flag --print: H (intestazioni della richiesta), B (corpo della richiesta), h (intestazioni della risposta), b (corpo della risposta). La combinazione --print=hb produce solo intestazioni e corpo della risposta, escludendo le meta-informazioni della connessione. Il flag --pretty=all attiva la formattazione a colori con rientri per la leggibilità.

Schemi di colori personalizzati

Httpie supporta la personalizzazione dei colori tramite la variabile d'ambiente HTTPIE_COLORS. Puoi configurare i colori per URL, intestazioni, chiavi JSON e codici di stato della risposta. Sono disponibili temi integrati: autumn, borland, fruity, monokai, native e tango per diversi tipi di terminali e preferenze personali.

Output in formato JSON senza formattazione

Per l'elaborazione programmatica dell'output, usa la combinazione di flag --body --pretty=none, che restituisce JSON grezzo senza colori e rientri. L'output compatto è utile per passarlo a jq, sed e altri parser da console durante l'automazione dei test API REST negli script shell.