TOC

Um Guia para Unirest

Um Guia para Unirest

1. Visão geral

O Unirest é uma biblioteca cliente HTTP leve da Mashape. Junto com Java, também está disponível para Node.js, .Net, Python, Ruby, etc.

Antes de começarmos, observe que usaremosmocky.io para todas as nossas solicitações HTTP aqui.

2. Configuração do Maven

Para começar, vamos adicionar as dependências necessárias primeiro: 


    com.mashape.unirest
    unirest-java
    1.4.9

Verifique a versão mais recentehere.

3. Pedidos Simples

Vamos enviar uma solicitação HTTP simples, para entender a semântica do 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());
}

Observe que a API é fluente, eficiente e bastante fácil de ler.

Estamos passando cabeçalhos e parâmetros com as APIsheader()efields().

E a solicitação é invocada na chamada do métodoasJson(); também temos outras opções aqui, comoasBinary(), asString()easObject().

Para passar vários cabeçalhos ou campos, podemos criar um mapa e passá-los para.headers(Map<String, Object> headers) e.fields(Map<String, String> fields) respectivamente: 

@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. Passando parâmetros de consulta

Para passar dados como uma consultaString,, usaremos o métodoqueryString(): 

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

3.2. Usando parâmetros de caminho

Para passar quaisquer parâmetros de URL, podemos usar o métodorouteParam(): 

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

O nome do espaço reservado para o parâmetro deve ser o mesmo que o primeiro argumento para o método

3.3. Solicitações com corpo

Se nossa solicitação requer uma string / corpo JSON, nós a passamos usando o métodobody(): 

@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. Mapeador de Objetos

Para usarasObject() oubody() na solicitação, precisamos definir nosso mapeador de objetos. Para simplificar, usaremos o mapeador de objetos Jackson.

Vamos primeiro adicionar as seguintes dependências apom.xml: 


    com.fasterxml.jackson.core
    jackson-databind
    2.9.4

Sempre use a versão mais recente acima deon Maven Central.

Agora vamos configurar nosso mapeador: 

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

Observe quesetObjectMapper() deve ser chamado apenas uma vez, para definir o mapeador; assim que a instância do mapeador for definida, ela será usada para todas as solicitações e respostas.

Agora vamos testar a nova funcionalidade usando um objetoArticle personalizado: 

@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étodos de solicitação

Semelhante a qualquer cliente HTTP, a estrutura fornece métodos separados para cada verbo HTTP:

POSTAR: 

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")

EXCLUIR: 

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

FRAGMENTO: 

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

OPÇÕES: 

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

5. Métodos de Resposta

Assim que recebermos a resposta, verifique o código e a mensagem de status: 

//...
jsonResponse.getStatus()

//...

Extraia os cabeçalhos: 

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

Obtenha o corpo da resposta: 

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

Observe quegetRawBody(), retorna um fluxo do corpo de resposta não analisado, enquantogetBody() retorna o corpo analisado, usando o mapeador de objetos definido na seção anterior.

6. Tratamento de solicitações assíncronas

O Unirest também tem a capacidade de lidar com solicitações assíncronas - usandojava.util.concurrent.Futuree métodos de retorno de chamada: 

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

A interfacecom.mashape.unirest.http.async.Callback<T> fornece três métodos,failed(),cancelled()ecompleted().

Substitua os métodos para executar as operações necessárias, dependendo da resposta.

7. Uploads de arquivos

Para fazer upload ou enviar um arquivo como parte da solicitação, passe um objetojava.io.File como um campo com nome de arquivo: 

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

Também podemos usarByteStream: 

@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 use o fluxo de entrada diretamente, adicionandoContentType.APPLICATION_OCTET_STREAM como o segundo argumento no métodofields(): 

@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. Configurações Unirest

A estrutura também suporta configurações típicas de um cliente HTTP, como pool de conexões, tempos limites, cabeçalhos globais etc.

Vamos definir o número de conexões e o número máximo de conexões por rota: 

Unirest.setConcurrency(20, 5);

Configure o tempo limite de conexão e soquete: 

Unirest.setTimeouts(20000, 15000);

Observe que os valores de tempo estão em milissegundos.

Agora vamos definir cabeçalhos HTTP para todas as nossas solicitações: 

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

Podemos limpar os cabeçalhos globais a qualquer momento: 

Unirest.clearDefaultHeaders();

Em algum momento, talvez seja necessário fazer solicitações por meio de um servidor proxy: 

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

Um aspecto importante a ser observado é fechar ou sair do aplicativo normalmente. Unirest gera um loop de evento em segundo plano para manipular as operações, precisamos encerrar esse loop antes de sair do aplicativo: 

Unirest.shutdown();

9. Conclusão

Neste tutorial, focamos na estrutura leve do cliente HTTP - Unirest. Trabalhamos com alguns exemplos simples, tanto nos modos síncrono quanto assíncrono.

Por fim, também usamos várias configurações avançadas - como pool de conexão, configurações de proxy etc.

Como de costume, o código-fonte está disponívelover on GitHub.

Related