Generatore di comandi curl
Indicando in un modulo il metodo HTTP, l'indirizzo, le intestazioni, il corpo e il tipo di autenticazione, genera un comando curl pronto da copiare ed eseguire. La richiesta non viene realmente inviata, perciò non incontra le restrizioni della condivisione fra origini diverse.
Le opzioni di curl usate più di frequente
| Opzione | Descrizione |
|---|---|
| -X, --request <metodo> | Indica il metodo HTTP: GET, POST, PUT, PATCH, DELETE e simili. Se omessa, il metodo è GET in assenza di corpo e POST in sua presenza. |
| -H, --header <intestazione> | Aggiunge un'intestazione alla richiesta. Per indicarne più di una si ripete l'opzione -H. |
| -d, --data <dati> | Invia il corpo della richiesta. Se non si indica -X, l'invio avviene automaticamente come POST con tipo di contenuto application/x-www-form-urlencoded. |
| -u, --user <utente:parola> | Indica nome utente e parola d'ordine per l'autenticazione di base, nella forma «utente:parola». |
| -k, --insecure | Salta la verifica del certificato SSL. Pensata per gli ambienti di sviluppo con certificati autofirmati; sconsigliata in produzione. |
| -L, --location | Se il servente risponde con un reindirizzamento della serie 3xx, segue automaticamente la destinazione indicata nell'intestazione Location. |
| -v, --verbose | Mostra sull'uscita d'errore standard lo scambio dettagliato, comprese le intestazioni di richiesta e risposta. Utile per la messa a punto. |
| --compressed | Aggiunge l'intestazione Accept-Encoding, richiede risposte compresse, per esempio in gzip, e le decomprime automaticamente. |
| -o, --output <file> | Salva il corpo della risposta nel file indicato anziché sull'uscita standard. |
| -F, --form <nome=contenuto> | Invia dati di modulo e file nel formato multipart/form-data. Per caricare un file si indica «@percorso-del-file». |
Comporre un comando curl da un modulo
Indicate nel modulo il metodo, l'indirizzo, le intestazioni, il corpo e l'autenticazione e ne esce un comando curl pronto da incollare in un terminale. Questo strumento non invia mai davvero la richiesta, sicché non è vincolato dalle restrizioni CORS del browser: il comando si compone anche per un'API che rifiuterebbe una richiesta partita da una pagina.
Ciò che fa inciampare con curl è il rapporto fra metodo e corpo. Allegate un corpo con -d e il metodo diventa POST da sé, anche se non ne avete scritto alcuno. Voler mandare un PUT o un PATCH fornendo il solo -d fa dunque partire un POST non voluto. L'altro errore frequente consiste nel mandare JSON dimenticando Content-Type: application/json; curl lo spedisce allora come application/x-www-form-urlencoded, e il server non lo legge affatto come JSON. Nell'incollare il comando generato in un terminale, badate anche alle virgolette della shell: entro gli apici le variabili non vengono sostituite, entro le virgolette doppie sì.
Come si usa
- Indicate il metodo e l'indirizzo Scegliete GET per prelevare e POST per inviare.
-
Aggiungete le vostre intestazioni
Se inviate JSON, non dimenticate
Content-Type: application/json. - Scrivete il corpo Allegare un corpo rende il metodo POST da sé là dove nessuno fosse indicato.
- Copiate il comando ed eseguitelo Incollarlo in un terminale è quanto basta.
Consigli per sfruttarlo al meglio
- Il comando generato si può incollare ed eseguire direttamente in un terminale, in uno script di shell o in un file di configurazione dell'integrazione continua. Tutti i valori sono già protetti con apici semplici.
- Se lasciate il metodo su GET e inserite un corpo compare un avviso. curl, infatti, quando si usa
-dsenza-X, invia automaticamente come POST: la segnalazione serve a evitare comportamenti indesiderati. - Spuntando l'aggiunta automatica dell'intestazione Content-Type: application/json, quella intestazione — che nelle richieste alle interfacce JSON si dimentica facilmente — viene inserita da sé.
- I valori dell'autenticazione di base e del gettone al portatore vengono elaborati soltanto nel navigatore e non sono mai trasmessi ad alcun servente.
- L'opzione
-k, che salta la verifica del certificato, è un espediente temporaneo riservato agli ambienti di sviluppo locali con certificati autofirmati. Evitatene l'uso stabile verso le interfacce di produzione.
Quando torna utile
Nel provare il comportamento di un'API
Un'API che non potete chiamare dal browser si può provare ugualmente con curl, senza che il CORS vi si opponga.
Nel porre un comando in una procedura
Potete mettere a verbale in che cosa consista una richiesta, in una forma che chiunque riproduca.
Nel condividere i passi per riprodurre un guasto
Consegnare a qualcuno un comando da eseguire dà una riproduzione assai meno toccata dalle differenze d'ambiente.
Nell'apprendere le opzioni di curl
Potete vedere in quale opzione si trasformi ciascun campo del modulo.
Termini di curl
- -X
- Indica il metodo in modo esplicito. Poiché
-dlo rende POST anche se omesso, è questo che occorre per PUT o DELETE. - -H
- Aggiunge un'intestazione. Scritto più volte, ne allega altrettante.
- -d
- Indica il corpo della richiesta. Scriverlo rende il metodo POST, e il tipo di contenuto predefinito diventa la codifica del modulo.
- -u
- Indica nome utente e parola d'ordine dell'autenticazione di base, scritti come
utente:parola. - Token Bearer
- Il procedimento che invia le credenziali come
Authorization: Bearer .... Moltissime API adottano questa forma. - -i e -v
- Mostrano le intestazioni di risposta e i particolari dello scambio. L'uno e l'altro si guadagnano il posto quando qualcosa non va.
Domande frequenti
-d, cioè il corpo, senza l'opzione -X, curl invia automaticamente come POST. Nei casi particolari in cui volete mantenere GET e inviare comunque un corpo, aggiungete a mano -X GET al comando generato.
A proposito — perché curl è lo strumento «che tutti usano e nessuno conosce»
curl è uno strumento a riga di comando per trasferire dati tramite indirizzi web, sviluppato nel 1996 dall'ingegnere svedese Daniel Stenberg. All'origine c'era un piccolo programma che recuperava i cambi valutari per un automa di conversazione su IRC; da lì è cresciuto fino a diventare un progetto imponente, capace di gestire oltre venticinque protocolli fra cui HTTP, FTP e SMTP.
curl è considerato uno dei programmi più diffusi al mondo. È incorporato in ogni sorta di apparecchio collegato a Internet — telefoni, automobili, elettrodomestici, console per videogiochi e persino sonde spaziali, con un impiego documentato nelle missioni marziane della NASA — e le stime parlano di decine di miliardi di dispositivi. Nonostante tanta diffusione, fuori dalla cerchia degli sviluppatori il suo nome è quasi ignoto: è l'esempio per eccellenza dell'infrastruttura che lavora nell'ombra.
Nel 2017 Stenberg ha ricevuto il Premio Polhem, il più antico riconoscimento svedese per l'ingegneria, per il suo lavoro su curl. Ancora oggi guida lo sviluppo di curl come principale responsabile della manutenzione ed è noto per aver condotto il progetto con grande cautela, senza mai rompere la compatibilità all'indietro in oltre vent'anni.
Anche oggi che Postman e le sue interfacce grafiche si sono affermate, i comandi curl continuano a comparire nei file di presentazione dei progetti, nella documentazione ufficiale e nelle procedure di verifica delle interfacce di programmazione. La ragione è semplice: curl non richiede installazione, è presente di serie in quasi tutti gli ambienti Linux e macOS e permette di eseguire e condividere un risultato con un solo comando, garantendo così un'elevata riproducibilità.