Un guide pour Unirest

1. Vue d'ensemble

Unirest est une bibliothèque client HTTP légère de Mashape. Avec Java, il est également disponible pour Node.js, .Net, Python, Ruby, etc.

Avant de nous lancer, notez que nous utiliseronsmocky.io pour toutes nos requêtes HTTP ici.

2. Maven Setup

Pour commencer, ajoutons d'abord les dépendances nécessaires:


    com.mashape.unirest
    unirest-java
    1.4.9

Découvrez la dernière versionhere.

3. Demandes simples

Envoyons une simple requête HTTP, pour comprendre la sémantique du framework:

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

    assertNotNull(jsonResponse.getBody());
    assertEquals(200, jsonResponse.getStatus());
}

Notez que l’API est fluide, efficace et assez facile à lire.

Nous transmettons des en-têtes et des paramètres avec les APIheader() etfields().

Et la demande est invoquée lors de l'appel de méthodeasJson(); nous avons également d'autres options ici, telles queasBinary(), asString() etasObject().

Pour passer plusieurs en-têtes ou champs, nous pouvons créer une carte et les transmettre respectivement à.headers(Map<String, Object> headers) et.fields(Map<String, String> fields):

@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 example");
    fields.put("id", "PSP123");

    HttpResponse jsonResponse
      = Unirest.put("http://www.mocky.io/v2/5a9ce7853100002a00ab515e")
      .headers(headers).fields(fields)
      .asJson();

    assertNotNull(jsonResponse.getBody());
    assertEquals(202, jsonResponse.getStatus());
}

3.1. Passer des paramètres de requête

Pour transmettre des données sous forme de requêteString,, nous utiliserons la méthodequeryString():

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

3.2. Utilisation des paramètres de chemin

Pour passer des paramètres d'URL, nous pouvons utiliser la méthoderouteParam():

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

Le nom d'espace réservé du paramètre doit être identique au premier argument de la méthode.

3.3. Demandes avec corps

Si notre requête nécessite une chaîne / un corps JSON, nous la transmettons à l'aide de la méthodebody():

@Test
public void givenRequestBodyWhenCreatedThenCorrect() {

    HttpResponse jsonResponse
      = Unirest.post("http://www.mocky.io/v2/5a9ce7663100006800ab515d")
      .body("{\"name\":\"Sam example\", \"city\":\"viena\"}")
      .asJson();

    assertEquals(201, jsonResponse.getStatus());
}

3.4. Mappeur d'objets

Afin d'utiliser lesasObject() oubody() dans la requête, nous devons définir notre mappeur d'objets. Pour plus de simplicité, nous utiliserons le mappeur d'objets Jackson.

Ajoutons d'abord les dépendances suivantes àpom.xml:


    com.fasterxml.jackson.core
    jackson-databind
    2.9.4

Utilisez toujours la dernière version suron Maven Central.

Configurons maintenant notre mappeur:

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);
    }
});

Notez quesetObjectMapper() ne doit être appelé qu'une seule fois, pour définir le mappeur; une fois que l'instance du mappeur est définie, elle sera utilisée pour toutes les demandes et réponses.

Testons maintenant la nouvelle fonctionnalité à l'aide d'un objetArticle personnalisé:

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

    assertEquals(201, jsonResponse.getStatus());
}

4. Méthodes de demande

Semblable à tout client HTTP, le framework fournit des méthodes séparées pour chaque verbe HTTP:

POSTER:

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

PUT:

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

GET:

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

EFFACER:

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

PIÈCE:

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

LES OPTIONS:

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

5. Méthodes de réponse

Une fois la réponse obtenue, vérifions le code d'état et le message d'état:

//...
jsonResponse.getStatus()

//...

Extraire les en-têtes:

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

Obtenez le corps de la réponse:

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

Notez quegetRawBody(), renvoie un flux du corps de réponse non analysé, tandis quegetBody() renvoie le corps analysé, en utilisant le mappeur d'objets défini dans la section précédente.

6. Gestion des demandes asynchrones

Unirest a également la capacité de gérer les requêtes asynchrones - en utilisantjava.util.concurrent.Future et les méthodes de rappel:

@Test
public void whenAysncRequestShouldReturnOk() {
    Future> future = Unirest.post(
      "http://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());
}

L'interfacecom.mashape.unirest.http.async.Callback<T> propose trois méthodes,failed(),cancelled() etcompleted().

Remplacez les méthodes pour effectuer les opérations nécessaires en fonction de la réponse.

7. Téléchargements de fichiers

Pour télécharger ou envoyer un fichier dans le cadre de la requête, transmettez un objetjava.io.File en tant que champ avec fichier de nom:

@Test
public void givenFileWhenUploadedThenCorrect() {

    HttpResponse jsonResponse = Unirest.post(
      "http://www.mocky.io/v2/5a9ce7663100006800ab515d")
      .field("file", new File("/path/to/file"))
      .asJson();

    assertEquals(201, jsonResponse.getStatus());
}

On peut aussi utiliserByteStream:

@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(
          "http://www.mocky.io/v2/5a9ce7663100006800ab515d")
          .field("file", bytes, "article.txt")
          .asJson();

        assertEquals(201, jsonResponse.getStatus());
    }
}

Ou utilisez directement le flux d'entrée, en ajoutant lesContentType.APPLICATION_OCTET_STREAM comme deuxième argument dans la méthodefields():

@Test
public void givenInputStreamWhenUploadedThenCorrect() {
    try (InputStream inputStream = new FileInputStream(
      new File("/path/to/file/artcile.txt"))) {

        HttpResponse jsonResponse = Unirest.post(
          "http://www.mocky.io/v2/5a9ce7663100006800ab515d")
          .field("file", inputStream, ContentType.APPLICATION_OCTET_STREAM, "article.txt").asJson();

        assertEquals(201, jsonResponse.getStatus());
    }
}

8. Configurations Unirest

L'infrastructure prend également en charge les configurations typiques d'un client HTTP telles que le regroupement de connexions, les délais d'attente, les en-têtes globaux, etc.

Définissons le nombre de connexions et le nombre maximum de connexions par itinéraire:

Unirest.setConcurrency(20, 5);

Configurez les délais de connexion et de socket:

Unirest.setTimeouts(20000, 15000);

Notez que les valeurs de temps sont en millisecondes.

Maintenant, définissons les en-têtes HTTP pour toutes nos requêtes:

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

Nous pouvons effacer les en-têtes globaux à tout moment:

Unirest.clearDefaultHeaders();

À un moment donné, nous pourrions avoir besoin de faire des demandes via un serveur proxy:

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

Un aspect important à prendre en compte est la fermeture ou la fermeture de l'application en douceur. Unirest génère une boucle d'événement en arrière-plan pour gérer les opérations. Nous devons fermer cette boucle avant de quitter notre application:

Unirest.shutdown();

9. Conclusion

Dans ce tutoriel, nous nous sommes concentrés sur la structure cliente HTTP légère - Unirest. Nous avons travaillé avec quelques exemples simples, à la fois en mode synchrone mais également en mode asynchrone.

Enfin, nous avons également utilisé plusieurs configurations avancées - telles que le regroupement de connexions, les paramètres de proxy, etc.

Comme d'habitude, le code source est disponibleover on GitHub.

TOC

Un guide pour Unirest