Una guida a Unirest

1. Panoramica

Unirest è una libreria client HTTP leggera di Mashape. Insieme a Java, è disponibile anche per Node.js, .Net, Python, Ruby, ecc.

Prima di saltare, nota che useremo mocky.io per tutte le nostre richieste HTTP qui.

2. Installazione di Maven

Per iniziare, aggiungiamo prima le dipendenze necessarie:

 com.mashape.unirest unirest-java 1.4.9 

Dai un'occhiata all'ultima versione qui.

3. Richieste semplici

Inviamo una semplice richiesta HTTP, per comprendere la semantica del framework:

@Test public void shouldReturnStatusOkay() { HttpResponse jsonResponse = Unirest.get("//www.mocky.io/v2/5a9ce37b3100004f00ab5154") .header("accept", "application/json").queryString("apiKey", "123") .asJson(); assertNotNull(jsonResponse.getBody()); assertEquals(200, jsonResponse.getStatus()); }

Si noti che l'API è fluente, efficiente e abbastanza facile da leggere.

Stiamo passando intestazioni e parametri con le API header () e fields () .

E la richiesta viene invocata sulla chiamata al metodo asJson () ; abbiamo anche altre opzioni qui, come asBinary (), asString () e asObject ().

Per passare più intestazioni o campi, possiamo creare una mappa e passarli rispettivamente a .headers (intestazioni mappa) e .fields (campi mappa) :

@Test public void shouldReturnStatusAccepted() { Map headers = new HashMap(); headers.put("accept", "application/json"); headers.put("Authorization", "Bearer 5a9ce37b3100004f00ab5154"); Map fields = new HashMap(); fields.put("name", "Sam Baeldung"); fields.put("id", "PSP123"); HttpResponse jsonResponse = Unirest.put("//www.mocky.io/v2/5a9ce7853100002a00ab515e") .headers(headers).fields(fields) .asJson(); assertNotNull(jsonResponse.getBody()); assertEquals(202, jsonResponse.getStatus()); }

3.1. Passaggio dei parametri di query

Per passare i dati come stringa di query , utilizzeremo il metodo queryString () :

HttpResponse jsonResponse = Unirest.get("//www.mocky.io/v2/5a9ce37b3100004f00ab5154") .queryString("apiKey", "123")

3.2. Utilizzo dei parametri di percorso

Per passare qualsiasi parametro URL, possiamo utilizzare il metodo routeParam () :

HttpResponse jsonResponse = Unirest.get("//www.mocky.io/v2/5a9ce37b3100004f00ab5154/{userId}") .routeParam("userId", "123")

Il nome del segnaposto del parametro deve essere uguale al primo argomento del metodo.

3.3. Richieste con corpo

Se la nostra richiesta richiede una stringa / corpo JSON, la passiamo utilizzando il metodo body () :

@Test public void givenRequestBodyWhenCreatedThenCorrect() { HttpResponse jsonResponse = Unirest.post("//www.mocky.io/v2/5a9ce7663100006800ab515d") .body("{\"name\":\"Sam Baeldung\", \"city\":\"viena\"}") .asJson(); assertEquals(201, jsonResponse.getStatus()); }

3.4. Object Mapper

Per poter usare asObject () o body () nella richiesta, dobbiamo definire il nostro mappatore di oggetti. Per semplicità, useremo il mappatore di oggetti Jackson.

Aggiungiamo prima le seguenti dipendenze a pom.xml :

 com.fasterxml.jackson.core jackson-databind 2.9.4 

Usa sempre l'ultima versione su Maven Central.

Ora configuriamo il nostro mappatore:

Unirest.setObjectMapper(new ObjectMapper() { com.fasterxml.jackson.databind.ObjectMapper mapper = new com.fasterxml.jackson.databind.ObjectMapper(); public String writeValue(Object value) { return mapper.writeValueAsString(value); } public  T readValue(String value, Class valueType) { return mapper.readValue(value, valueType); } });

Notare che setObjectMapper () dovrebbe essere chiamato solo una volta, per impostare il mapper; una volta impostata, l'istanza del mapper verrà utilizzata per tutte le richieste e le risposte.

Proviamo ora la nuova funzionalità utilizzando un oggetto Articolo personalizzato :

@Test public void givenArticleWhenCreatedThenCorrect() { Article article = new Article("ID1213", "Guide to Rest", "baeldung"); HttpResponse jsonResponse = Unirest.post("//www.mocky.io/v2/5a9ce7663100006800ab515d") .body(article) .asJson(); assertEquals(201, jsonResponse.getStatus()); }

4. Metodi di richiesta

Simile a qualsiasi client HTTP, il framework fornisce metodi separati per ogni verbo HTTP:

INVIARE:

Unirest.post("//www.mocky.io/v2/5a9ce7663100006800ab515d")

METTERE:

Unirest.put("//www.mocky.io/v2/5a9ce7663100006800ab515d")

OTTENERE:

Unirest.get("//www.mocky.io/v2/5a9ce7663100006800ab515d")

ELIMINA:

Unirest.delete("//www.mocky.io/v2/5a9ce7663100006800ab515d")

PATCH:

Unirest.patch("//www.mocky.io/v2/5a9ce7663100006800ab515d")

OPZIONI:

Unirest.options("//www.mocky.io/v2/5a9ce7663100006800ab515d")

5. Metodi di risposta

Una volta ottenuta la risposta, controlliamo il codice di stato e il messaggio di stato:

//... jsonResponse.getStatus() //...

Estrai le intestazioni:

//... jsonResponse.getHeaders(); //...

Ottieni il corpo della risposta:

//... jsonResponse.getBody(); jsonResponse.getRawBody(); //...

Si noti che, getRawBody (), restituisce un flusso del corpo della risposta non analizzato, mentre getBody () restituisce il corpo analizzato, utilizzando il mappatore oggetto definito nella sezione precedente.

6. Gestione delle richieste asincrone

Unirest ha anche la capacità di gestire richieste asincrone - utilizzando java.util.concurrent.Future e metodi di callback:

@Test public void whenAysncRequestShouldReturnOk() { Future
    
      future = Unirest.post( "//www.mocky.io/v2/5a9ce37b3100004f00ab5154?mocky-delay=10000ms") .header("accept", "application/json") .asJsonAsync(new Callback() { public void failed(UnirestException e) { // Do something if the request failed } public void completed(HttpResponse response) { // Do something if the request is successful } public void cancelled() { // Do something if the request is cancelled } }); assertEquals(200, future.get().getStatus()); }
    

The com.mashape.unirest.http.async.Callback interface provides three methods, failed(), cancelled() and completed().

Override the methods to perform the necessary operations depending on the response.

7. File Uploads

To upload or send a file as a part of the request, pass a java.io.File object as a field with name file:

@Test public void givenFileWhenUploadedThenCorrect() { HttpResponse jsonResponse = Unirest.post( "//www.mocky.io/v2/5a9ce7663100006800ab515d") .field("file", new File("/path/to/file")) .asJson(); assertEquals(201, jsonResponse.getStatus()); }

We can also use ByteStream:

@Test public void givenByteStreamWhenUploadedThenCorrect() { try (InputStream inputStream = new FileInputStream( new File("/path/to/file/artcile.txt"))) { byte[] bytes = new byte[inputStream.available()]; inputStream.read(bytes); HttpResponse jsonResponse = Unirest.post( "//www.mocky.io/v2/5a9ce7663100006800ab515d") .field("file", bytes, "article.txt") .asJson(); assertEquals(201, jsonResponse.getStatus()); } }

Or use the input stream directly, adding the ContentType.APPLICATION_OCTET_STREAM as the second argument in the fields() method:

@Test public void givenInputStreamWhenUploadedThenCorrect() { try (InputStream inputStream = new FileInputStream( new File("/path/to/file/artcile.txt"))) { HttpResponse jsonResponse = Unirest.post( "//www.mocky.io/v2/5a9ce7663100006800ab515d") .field("file", inputStream, ContentType.APPLICATION_OCTET_STREAM, "article.txt").asJson(); assertEquals(201, jsonResponse.getStatus()); } }

8. Unirest Configurations

The framework also supports typical configurations of an HTTP client like connection pooling, timeouts, global headers etc.

Let's set the number of connections and number maximum connections per route:

Unirest.setConcurrency(20, 5);

Configure connection and socket timeouts :

Unirest.setTimeouts(20000, 15000);

Note that the time values are in milliseconds.

Now let's set HTTP headers for all our requests:

Unirest.setDefaultHeader("X-app-name", "baeldung-unirest"); Unirest.setDefaultHeader("X-request-id", "100004f00ab5");

We can clear the global headers anytime:

Unirest.clearDefaultHeaders();

At some point, we might need to make requests through a proxy server:

Unirest.setProxy(new HttpHost("localhost", 8080));

One important aspect to be aware of is closing or exiting the application gracefully. Unirest spawns a background event loop to handle the operations, we need to shut down that loop before exiting our application:

Unirest.shutdown();

9. Conclusion

In this tutorial, we focused on the lightweight HTTP client framework – Unirest. We worked with some simple examples, both in a synchronous but also async modes.

Finally, we also used several advanced configurations – such as connection pooling, proxy settings etc.

Come al solito, il codice sorgente è disponibile su GitHub.