Prova un'API REST con curl

1. Panoramica

Questo tutorial offre una breve panoramica del test di un'API REST utilizzando curl.

curl è uno strumento da riga di comando per il trasferimento dei dati e supporta circa 22 protocolli incluso HTTP. Questa combinazione lo rende un ottimo strumento ad-hoc per testare i nostri servizi REST.

2. Opzioni della riga di comando

curl supporta oltre 200 opzioni della riga di comando . E possiamo averne zero o più per accompagnare l'URL nel comando.

Ma prima di usarlo per i nostri scopi, diamo un'occhiata a due che renderebbero le nostre vite più facili.

2.1. Verbose

Quando stiamo testando, è una buona idea impostare la modalità dettagliata su:

curl -v //www.example.com/

Di conseguenza, i comandi fornirebbero informazioni utili come l'indirizzo IP risolto, la porta a cui stiamo tentando di connetterci e le intestazioni.

2.2. Produzione

Per impostazione predefinita, curl restituisce il corpo della risposta allo standard output. Facoltativamente, possiamo fornire l'opzione di output per salvare in un file:

curl -o out.json //www.example.com/index.html

Ciò è particolarmente utile quando la dimensione della risposta è grande.

3. Metodi HTTP con Curl

Ogni richiesta HTTP contiene un metodo. I metodi più comunemente usati sono GET, POST, PUT e DELETE.

3.1. OTTENERE

Questo è il metodo predefinito quando si effettuano chiamate HTTP con curl. In effetti, gli esempi mostrati in precedenza erano semplici chiamate GET.

Durante l'esecuzione di un'istanza locale di un servizio sulla porta 8082, useremmo qualcosa di simile a questo comando per effettuare una chiamata GET:

curl -v //localhost:8082/spring-rest/foos/9

E poiché abbiamo la modalità dettagliata attiva, avremmo un po 'più di informazioni insieme al corpo della risposta:

* Trying ::1... * TCP_NODELAY set * Connected to localhost (::1) port 8082 (#0) > GET /spring-rest/foos/9 HTTP/1.1 > Host: localhost:8082 > User-Agent: curl/7.60.0 > Accept: */* >< HTTP/1.1 200 < X-Application-Context: application:8082 < Content-Type: application/json;charset=UTF-8 < Transfer-Encoding: chunked < Date: Sun, 15 Jul 2018 11:55:26 GMT < { "id" : 9, "name" : "TuwJ" }* Connection #0 to host localhost left intact

3.2. INVIARE

Utilizziamo questo metodo per inviare dati a un servizio di ricezione. E per questo, usiamo l'opzione dati.

Il modo più semplice per farlo è incorporare i dati nel comando:

curl -d 'id=9&name=baeldung' //localhost:8082/spring-rest/foos/new

oppure, passa un file contenente il corpo della richiesta all'opzione dati in questo modo:

curl -d @request.json -H "Content-Type: application/json" //localhost:8082/spring-rest/foos/new

Utilizzando i comandi precedenti così come sono, potremmo incappare in messaggi di errore come il seguente:

{ "timestamp" : "15-07-2018 05:57", "status" : 415, "error" : "Unsupported Media Type", "exception" : "org.springframework.web.HttpMediaTypeNotSupportedException", "message" : "Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported", "path" : "/spring-rest/foos/new" }

Questo perché curl aggiunge la seguente intestazione predefinita a tutte le richieste POST:

Content-Type: application/x-www-form-urlencoded

Questo è anche ciò che i browser usano in un semplice POST. Nel nostro utilizzo, di solito vorremmo personalizzare le intestazioni in base alle nostre esigenze.

Ad esempio, se il nostro servizio prevede il tipo di contenuto json, possiamo utilizzare l'opzione -H per modificare la nostra richiesta POST originale:

curl -d '{"id":9,"name":"baeldung"}' -H 'Content-Type: application/json' //localhost:8082/spring-rest/foos/new

Il prompt dei comandi di Windows non supporta le virgolette singole come le shell di tipo Unix.

Di conseguenza, avremmo bisogno di sostituire le virgolette singole con virgolette doppie; sfuggendoli dove necessario:

curl -d "{\"id\":9,\"name\":\"baeldung\"}" -H "Content-Type: application/json" //localhost:8082/spring-rest/foos/new

Inoltre, quando vogliamo inviare una quantità di dati leggermente maggiore, di solito è una buona idea utilizzare un file di dati.

3.3. METTERE

Questo metodo è molto simile a POST. Ma lo usiamo quando vogliamo inviare una nuova versione di una risorsa esistente. Per fare ciò, usiamo l'opzione -X.

Senza alcuna menzione di un tipo di metodo di richiesta, curl utilizza per impostazione predefinita GET. Pertanto, menzioniamo esplicitamente il tipo di metodo in caso di PUT:

curl -d @request.json -H 'Content-Type: application/json' -X PUT //localhost:8082/spring-rest/foos/9

3.4. ELIMINA

Ancora una volta, specifichiamo che vogliamo usare DELETE usando l'opzione -X:

curl -X DELETE //localhost:8082/spring-rest/foos/9

4. Intestazioni personalizzate

Possiamo sostituire le intestazioni predefinite o aggiungere le nostre intestazioni.

Ad esempio, per modificare l'intestazione Host, facciamo questo:

curl -H "Host: com.baeldung" //example.com/

Per disattivare l'intestazione User-Agent, inseriamo un valore vuoto:

curl -H "User-Agent:" //example.com/

Lo scenario più comune durante il test è la modifica dell'intestazione Content-Type e Accept. Dovremmo solo aggiungere il prefisso a ciascuna intestazione con l'opzione -H:

curl -d @request.json -H "Content-Type: application/json" -H "Accept: application/json" //localhost:8082/spring-rest/foos/new

5. Autenticazione

Un servizio che richiede l'autenticazione rispedirà un codice di risposta HTTP 401 - Non autorizzato e un'intestazione WWW-Authenticate associata.

Per l'autenticazione di base, possiamo semplicemente incorporare la combinazione di nome utente e password all'interno della nostra richiesta utilizzando l'opzione utente :

curl --user baeldung:secretPassword //example.com/

Tuttavia, se vogliamo utilizzare OAuth2 per l'autenticazione, dobbiamo prima ottenere access_token dal nostro servizio di autorizzazione.

La risposta del servizio conterrebbe access_token:

{ "access_token": "b1094abc0-54a4-3eab-7213-877142c33fh3", "token_type": "bearer", "refresh_token": "253begef-868c-5d48-92e8-448c2ec4bd91", "expires_in": 31234 }

Ora possiamo usare il token nella nostra intestazione di autorizzazione:

curl -H "Authorization: Bearer b1094abc0-54a4-3eab-7213-877142c33fh3" //example.com/

6. Conclusione

Abbiamo esaminato l'utilizzo della funzionalità minima di curl per testare i nostri servizi REST. Sebbene possa fare molto di più di quanto discusso qui, per il nostro scopo, questo dovrebbe bastare.

Sentiti libero di digitare curl -h sulla riga di comando per controllare tutte le opzioni disponibili. Il servizio REST utilizzato per la dimostrazione è disponibile qui su GitHub.