Integrazione dei proxy con i client REST API: configurazione di Postman, Insomnia, cURL e HTTPie

Durante lo sviluppo e il test di API, spesso sorge la necessità di inviare richieste tramite server proxy. Questo può essere necessario per aggirare restrizioni geografiche, testare il comportamento delle API da diverse regioni, garantire l'anonimato o lavorare con servizi che bloccano gli IP dei data center. In questa guida vedremo come configurare correttamente i proxy nei popolari client REST API ed evitare errori comuni.

Esamineremo quattro degli strumenti più popolari per lavorare con le API: Postman (interfaccia grafica per la maggior parte degli sviluppatori), Insomnia (un'alternativa moderna con un'interfaccia utente intuitiva), cURL (strumento classico da riga di comando) e HTTPie (client CLI moderno con sintassi leggibile). Per ciascuno strumento forniremo esempi di codice e discuteremo le peculiarità della configurazione.

Quali tipi di proxy sono adatti per lavorare con le API

Prima di configurare un proxy nei client API, è importante capire quale tipo di proxy è adatto per il tuo compito. I client REST API supportano due protocolli principali: HTTP/HTTPS e SOCKS5. La scelta dipende dai requisiti specifici dell'API e dal livello di sicurezza necessario.

I proxy HTTP/HTTPS operano a livello di protocollo HTTP e sono ideali per la maggior parte delle richieste REST API. Comprendono la struttura del traffico HTTP, possono memorizzare nella cache le risposte e modificare le intestazioni. I proxy HTTPS, inoltre, crittografano ulteriormente la connessione tra il client e il server proxy, il che è importante quando si trasmettono dati sensibili, come chiavi API o token di autorizzazione.

I proxy SOCKS5 operano a un livello inferiore e possono trasmettere qualsiasi tipo di traffico senza modifiche. Sono più lenti dei proxy HTTP, ma offrono una migliore anonimato e sono adatti per casi in cui l'API utilizza protocolli non standard o è necessaria una completa trasparenza della connessione. I SOCKS5 supportano anche il traffico UDP, anche se per le REST API questo è raro.

Configurazione del proxy in Postman: impostazioni globali e locali

Postman è lo strumento grafico più popolare per lavorare con le REST API, utilizzato da milioni di sviluppatori. Supporta due modi di configurare i proxy: impostazioni globali (applicate a tutte le richieste) e impostazioni a livello di ambiente. Esaminiamo entrambi i metodi in dettaglio.

Configurazione globale del proxy in Postman

Le impostazioni globali del proxy si trovano nel menu Impostazioni (icona dell'ingranaggio in alto a destra). Questo metodo è comodo quando si desidera che tutte le richieste da Postman passino sempre attraverso lo stesso server proxy. Ecco una guida passo passo:

1. Apri Postman e fai clic sull'icona dell'ingranaggio (Impostazioni) in alto a destra
2. Vai alla scheda "Proxy"
3. Attiva l'opzione "Aggiungi una configurazione proxy personalizzata"
4. Seleziona il tipo di proxy: HTTP, HTTPS o SOCKS5
5. Inserisci l'indirizzo del server proxy (ad esempio: proxy.example.com)
6. Specifica la porta (di solito 8080 per HTTP, 1080 per SOCKS5)
7. Se il proxy richiede autenticazione, attiva "Proxy Auth" e inserisci nome utente/password
8. Fai clic su "Salva" e chiudi la finestra delle impostazioni

Dopo aver fatto ciò, tutte le richieste da Postman passeranno automaticamente attraverso il proxy specificato. Una caratteristica importante: Postman invia anche telemetria e controlla gli aggiornamenti tramite il proxy, il che può generare traffico aggiuntivo. Se utilizzi un proxy con traffico limitato, è bene tenerne conto.

Configurazione del proxy tramite variabili di ambiente

Un modo più flessibile è utilizzare le variabili di ambiente. Questo consente di passare rapidamente tra diversi proxy per diversi progetti o API. Crea un nuovo ambiente e aggiungi le seguenti variabili:

PROXY_HOST = proxy.example.com
PROXY_PORT = 8080
PROXY_USER = your_username
PROXY_PASS = your_password

Quindi, nelle impostazioni globali del proxy, utilizza queste variabili invece di valori specifici: {{PROXY_HOST}} e {{PROXY_PORT}}. Ora puoi creare più ambienti (ad esempio, "Proxy di produzione", "Proxy di test", "Proxy USA") e passare tra di essi con un clic.

Utilizzo del proxy di sistema

Postman può anche utilizzare le impostazioni di proxy del sistema operativo. Per farlo, nelle impostazioni del proxy, seleziona l'opzione "Usa proxy di sistema". Questo è comodo se hai già configurato un proxy a livello di sistema (ad esempio, tramite le impostazioni di Windows o macOS) e desideri che Postman utilizzi le stesse impostazioni del browser.

Configurazione del proxy in Insomnia

Insomnia è un'alternativa moderna a Postman con un'interfaccia pulita e codice sorgente aperto. La configurazione del proxy in Insomnia è leggermente diversa da quella di Postman e richiede la modifica del file di configurazione o l'uso di variabili di ambiente. Esaminiamo entrambi i metodi.

Configurazione tramite variabili di ambiente

Il modo più semplice per configurare un proxy in Insomnia è utilizzare le variabili di ambiente standard HTTP_PROXY e HTTPS_PROXY. Insomnia legge automaticamente queste variabili dal sistema. Impostale prima di avviare Insomnia:

Linux/macOS:

export HTTP_PROXY="http://username:password@proxy.example.com:8080"
export HTTPS_PROXY="http://username:password@proxy.example.com:8080"
insomnia

Windows (PowerShell):

$env:HTTP_PROXY = "http://username:password@proxy.example.com:8080"
$env:HTTPS_PROXY = "http://username:password@proxy.example.com:8080"
insomnia

Nota il formato dell'URL: anche per i proxy HTTPS si utilizza lo schema http://, non https://. Questo è un accordo standard per le variabili di ambiente proxy. Se il proxy non richiede autenticazione, l'URL sarà più breve: http://proxy.example.com:8080.

Configurazione del proxy SOCKS5

Per i proxy SOCKS5 utilizza la variabile di ambiente ALL_PROXY:

export ALL_PROXY="socks5://username:password@proxy.example.com:1080"

Insomnia supporta SOCKS5, ma non tutte le versioni gestiscono correttamente l'autenticazione SOCKS5. Se hai problemi con SOCKS5 autenticati, prova a utilizzare un proxy HTTP o aggiorna Insomnia all'ultima versione.

Configurazione tramite file di configurazione

Per una configurazione permanente del proxy, puoi modificare il file di configurazione di Insomnia. La posizione del file dipende dal sistema operativo:

• Windows: %APPDATA%\Insomnia\config.json
• macOS: ~/Library/Application Support/Insomnia/config.json
• Linux: ~/.config/Insomnia/config.json

Apri il file in un editor di testo e aggiungi la sezione proxy:

{
  "proxy": {
    "http": "http://username:password@proxy.example.com:8080",
    "https": "http://username:password@proxy.example.com:8080"
  }
}

Dopo aver modificato, riavvia Insomnia. Le impostazioni del proxy si applicheranno automaticamente a tutte le richieste.

Utilizzo del proxy in cURL: esempi di comandi

cURL è uno strumento classico da riga di comando per lavorare con HTTP, installato praticamente su tutti i sistemi Unix-like e Windows 10+. Supporta i proxy tramite il parametro -x o --proxy. Esaminiamo vari scenari di utilizzo.

Utilizzo base del proxy HTTP

Un esempio semplice di utilizzo di un proxy HTTP senza autenticazione:

curl -x http://proxy.example.com:8080 https://api.example.com/users

Il parametro -x specifica l'indirizzo e la porta del server proxy. cURL determinerà automaticamente che si tratta di un proxy HTTP e configurerà la connessione. Se desideri specificare esplicitamente il protocollo, utilizza l'URL completo:

curl --proxy http://proxy.example.com:8080 https://api.example.com/users

Proxy con autenticazione

Se il proxy richiede autenticazione con nome utente e password, aggiungili all'URL del proxy o utilizza il parametro -U:

# Metodo 1: nome utente e password nell'URL
curl -x http://username:password@proxy.example.com:8080 https://api.example.com/users

# Metodo 2: parametro -U (più sicuro, non viene salvato nella cronologia dei comandi)
curl -x http://proxy.example.com:8080 -U username:password https://api.example.com/users

Il secondo metodo è preferibile, poiché nome utente e password non verranno salvati nella cronologia dei comandi della shell. Per ulteriore sicurezza, puoi specificare solo il nome utente, e cURL richiederà la password in modo interattivo:

curl -x http://proxy.example.com:8080 -U username https://api.example.com/users
# cURL richiederà la password: Inserisci la password del proxy per l'utente 'username':

Utilizzo di un proxy SOCKS5

Per i proxy SOCKS5 specifica esplicitamente il protocollo nell'URL:

# SOCKS5 senza autenticazione
curl -x socks5://proxy.example.com:1080 https://api.example.com/users

# SOCKS5 con autenticazione
curl -x socks5://username:password@proxy.example.com:1080 https://api.example.com/users

# SOCKS5h (risoluzione DNS tramite proxy)
curl -x socks5h://proxy.example.com:1080 https://api.example.com/users

La differenza tra socks5:// e socks5h://: nel primo caso la risoluzione DNS avviene localmente (sul tuo computer), nel secondo tramite il server proxy. Utilizza socks5h:// se desideri nascondere completamente le richieste DNS dal tuo provider.

Richieste POST tramite proxy

Il proxy funziona allo stesso modo per tutti i metodi HTTP. Ecco un esempio di richiesta POST con dati JSON tramite proxy:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}' \
  https://api.example.com/users

Per inviare file, utilizza il parametro -F:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -F "file=@document.pdf" \
  -F "description=Important document" \
  https://api.example.com/upload

Utilizzo di variabili di ambiente

Invece di specificare il proxy in ogni comando, puoi utilizzare variabili di ambiente. cURL legge automaticamente http_proxy, https_proxy e all_proxy:

# Imposta le variabili di ambiente
export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# Ora tutti i comandi cURL utilizzano automaticamente il proxy
curl https://api.example.com/users

# Disabilita il proxy per un comando specifico
curl --noproxy "*" https://api.example.com/users

Il parametro --noproxy consente di escludere domini specifici dal proxy. Ad esempio, per non utilizzare il proxy per localhost e domini interni:

export no_proxy="localhost,127.0.0.1,.internal.company.com"

Configurazione del proxy in HTTPie

HTTPie è un'alternativa moderna a cURL con sintassi leggibile e output colorato. È particolarmente utile per lavorare in modo interattivo con le API nel terminale. HTTPie supporta i proxy tramite il parametro --proxy o variabili di ambiente.

Utilizzo base del proxy

La sintassi di HTTPie per i proxy è leggermente diversa da quella di cURL. Devi specificare il protocollo e l'URL del proxy separatamente:

# Proxy HTTP
http --proxy=http:http://proxy.example.com:8080 \
     --proxy=https:http://proxy.example.com:8080 \
     GET https://api.example.com/users

# Forma abbreviata (se il proxy è lo stesso per HTTP e HTTPS)
http --proxy=all:http://proxy.example.com:8080 GET https://api.example.com/users

Formato: --proxy=protocol:proxy_url. Per le richieste HTTPS si utilizza generalmente un proxy HTTP (non HTTPS), questo è il comportamento standard.

Proxy con autenticazione

Per l'autenticazione, aggiungi nome utente e password all'URL del proxy:

http --proxy=all:http://username:password@proxy.example.com:8080 \
     GET https://api.example.com/users

HTTPie supporta anche il parametro --proxy-auth per specificare più esplicitamente le credenziali, ma nelle ultime versioni questo parametro è considerato obsoleto e si raccomanda di includere l'autenticazione nell'URL.

Proxy SOCKS5 in HTTPie

HTTPie supporta i proxy SOCKS5 a partire dalla versione 2.0.0. Assicurati di avere installata l'ultima versione:

# Controlla la versione di HTTPie
http --version

# Aggiorna HTTPie tramite pip
pip install --upgrade httpie

# Utilizza un proxy SOCKS5
http --proxy=all:socks5://proxy.example.com:1080 GET https://api.example.com/users

Per SOCKS5 con autenticazione sarà necessario installare una libreria aggiuntiva pysocks:

pip install pysocks
http --proxy=all:socks5://username:password@proxy.example.com:1080 \
     GET https://api.example.com/users

Richieste POST e invio di dati

HTTPie ha una sintassi comoda per le richieste POST. Ecco un esempio di invio di JSON tramite proxy:

# POST con JSON (HTTPie determina automaticamente il Content-Type)
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/users \
     name="John Doe" \
     email="john@example.com" \
     age:=30

# Invio di un file
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/upload \
     file@document.pdf \
     description="Important document"

Nota la sintassi: key=value per le stringhe, key:=value per numeri e valori booleani, key@file per i file.

Utilizzo di variabili di ambiente

Come cURL, HTTPie legge le variabili di ambiente standard http_proxy e https_proxy:

export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# Ora tutti i comandi utilizzano automaticamente il proxy
http GET https://api.example.com/users

Per disabilitare temporaneamente il proxy, utilizza il parametro --proxy= (valore vuoto):

http --proxy= GET https://api.example.com/users

Autenticazione del proxy: nome utente e password

La maggior parte dei servizi proxy commerciali richiede autenticazione per proteggere da utilizzi non autorizzati. Ci sono due metodi principali di autenticazione: Basic Authentication (nome utente/password) e IP Whitelist (associazione all'indirizzo IP). Esaminiamo le caratteristiche di ciascun metodo e come configurarli correttamente nei client API.

Basic Authentication (nome utente e password)

La Basic Authentication è il metodo più comune. Il server proxy richiede nome utente e password ad ogni connessione. Le credenziali vengono trasmesse nell'intestazione Proxy-Authorization in formato Base64. Tutti i moderni client API generano automaticamente questa intestazione se specifichi nome utente e password nell'URL del proxy.

Formato dell'URL con autenticazione:

protocol://username:password@proxy_host:proxy_port

Esempi per diversi protocolli:

# Proxy HTTP
http://user123:pass456@proxy.example.com:8080

# Proxy HTTPS (si utilizza lo stesso formato)
http://user123:pass456@proxy.example.com:8080

# Proxy SOCKS5
socks5://user123:pass456@proxy.example.com:1080

IP Whitelist (associazione all'IP)

Alcuni provider di proxy offrono autenticazione tramite indirizzo IP. In questo caso, aggiungi il tuo IP alla whitelist nel pannello di controllo del proxy e il server consente le connessioni solo da questo IP senza nome utente e password. Questo è più comodo e sicuro, poiché non è necessario trasmettere le credenziali in ogni richiesta.

Quando utilizzi la IP Whitelist, il formato dell'URL del proxy si semplifica:

# Senza nome utente e password
http://proxy.example.com:8080

# Esempio in cURL
curl -x http://proxy.example.com:8080 https://api.example.com/users

Lo svantaggio di questo metodo è che se il tuo IP è dinamico (cambia quando ti riconnetti a Internet), dovrai aggiornare ogni volta la whitelist. Per i server con IP statico, questa è l'opzione ideale.

Caratteri speciali nella password

Se la password del proxy contiene caratteri speciali (@, :, /, ?), devono essere codificati in formato URL encoding (percent encoding). Ad esempio:

Esempio di utilizzo di una password con caratteri speciali:

# Password originale: P@ss:w0rd/123
# Password codificata: P%40ss%3Aw0rd%2F123

curl -x http://username:P%40ss%3Aw0rd%2F123@proxy.example.com:8080 \
     https://api.example.com/users

Per la codifica automatica, puoi utilizzare strumenti online per l'URL encoder o un comando in Python:

python3 -c "import urllib.parse; print(urllib.parse.quote('P@ss:w0rd/123'))"
# Output: P%40ss%3Aw0rd%2F123

Risoluzione di problemi e errori comuni

Quando si lavora con proxy nei client API, si verificano spesso errori comuni. Esaminiamo i problemi più comuni e come risolverli.

Errore "407 Proxy Authentication Required"

Questo errore significa che il server proxy richiede autenticazione, ma le credenziali non sono state fornite o sono errate. Soluzioni:

• Controlla la correttezza di nome utente e password nel pannello di controllo del provider proxy
• Assicurati che i caratteri speciali nella password siano codificati (vedi sezione sopra)
• Controlla il formato dell'URL: http://username:password@host:port
• Se utilizzi la IP Whitelist, assicurati che il tuo IP attuale sia aggiunto alla whitelist

Esempio di diagnosi in cURL con output dettagliato:

curl -v -x http://username:password@proxy.example.com:8080 https://api.example.com/users
# Il flag -v (verbose) mostrerà tutte le intestazioni e il processo di autenticazione

Errore "Connection timeout" o "Failed to connect"

Questo errore si verifica quando il client API non riesce a stabilire una connessione con il server proxy. Possibili cause:

• Indirizzo o porta del server proxy errati — controlla le impostazioni con il provider
• Il server proxy non è disponibile o è sovraccarico — prova un altro server dalla lista
• Il tuo firewall blocca le connessioni in uscita sulla porta del proxy
• Il provider proxy ha bloccato il tuo IP per superamento dei limiti

Per la diagnosi, prova a connetterti al proxy direttamente tramite telnet o nc:

# Controllo della disponibilità del proxy
telnet proxy.example.com 8080
# oppure
nc -zv proxy.example.com 8080

# Se la connessione non si stabilisce, il problema è nella rete o il server proxy non è disponibile

Errore "SSL certificate problem"

Quando si utilizza un proxy HTTPS, possono verificarsi problemi con la verifica dei certificati SSL. Questo è particolarmente rilevante per i proxy MITM (Man-in-the-Middle) che intercettano e decrittografano il traffico HTTPS. Soluzioni:

• In cURL utilizza il flag -k o --insecure per disabilitare la verifica del certificato (solo per test!)
• In Postman disabilita "SSL certificate verification" in Impostazioni → Generale
• Installa il certificato radice del proxy nel sistema (per l'ambiente di produzione)

# Disabilita la verifica del certificato
curl -k -x http://username:password@proxy.example.com:8080 https://api.example.com/users

Migliori pratiche per lavorare con proxy nei client API

Ecco alcune migliori pratiche per lavorare con i proxy nei client API:

• Utilizza sempre proxy residenziali per evitare blocchi da parte delle API
• Configura correttamente l'autenticazione per garantire la sicurezza
• Monitora il traffico e le prestazioni del proxy per ottimizzare le richieste
• Utilizza variabili di ambiente per gestire facilmente le configurazioni di proxy
• Testa sempre le configurazioni in un ambiente di sviluppo prima di passare alla produzione

Conclusione

Configurare correttamente i proxy nei client REST API è fondamentale per garantire un accesso sicuro e senza interruzioni alle API. Seguendo le linee guida e le migliori pratiche descritte in questa guida, puoi ottimizzare il tuo flusso di lavoro e ridurre al minimo i problemi di connessione. Buona fortuna con le tue integrazioni API!