jHttpClient Introduction

Simplified Java Rest Http client library build on top of the new HttpClient delivered in Java 11.

Usage Reference

The jHttpClient library provides both Blocking and Non-Blocking version of a Rest Client.

Using the RestClient (Blocking)

In case you need simple Rest Client in a classic imperative code to call Rest API, then the RestClient is what you need.

Making requests

Here is an example how to do a simple GET request with the RestClient:

var restClient = new RestClient();
restClient.get("https://example.com/rest/endpoint");

Here is an example how to do a simple POST request with the RestClient:

var restClient = new RestClient();
var reqBody = "{\"test\": 1}";
restClient.post("https://example.com/rest/endpoint", reqBody);

Constructor

The default constructor creates an instance of the RestClient with common defaults: HTTP v1.1, No redirect from Https to Http, 30 Seconds timeout, UTF-8 charset and Content-Type: application/json header. You can overwrite, add new or remove headers that the RestClient is sending:

var restClient = new RestClient();
// We overwrite the Content-Type
restClient.addHeader("Content-Type", "text/plain");
// We add new header
restClient.addHeader("CustomHeader", "ExampleValue");
// We send an request
restClient.get("https://example.com/plain/text");
// We remove the custom header
restClient.removeHeader("CustomHeader");

In case the defaults don't suite your needs you can create instances of the RestClient with custom setting:

var customHeaders = Map.of("Content-Type", "application/json", "CustomName", "CustomValue");
var restClient = new RestClient(HttpClient.Version.HTTP_2, HttpClient.Redirect.ALWAYS, Duration.ofSeconds(10), customSslContect, customHeaders, StandardCharsets.ISO_8859_1);

Responses

The RestClient methods get, post, put, patch, delete return instances of StringResponse while head returns instance of NoBodyResponse

The StringResponse is Java Record that contains the body, response code and response headers:

record StringResponse(int code, Map<String, List<String>> headers, String body)

The NoBodyResponse is Java Record that contains only the response code and response headers:

record NoBodyResponse(int code, Map<String, List<String>> headers)

Using the RestJsonClient (Blocking) with JSON binding

Usually when integrating Java application with a Rest Web Service, usually an existing JSON binding library (like Jackson or JSONB) is used so we use POJO objects. To this end there is implemeted mechanism that will allow you to provide a custom Json mapper of your choice to integrate directly with the Rest Client.

Here is an example with JSONB:

// Implement the IObjectMapper interface 
class VerySimpleCustomMapper extends IObjectMapper {

    public CustomMapper() {
        Jsonb jsonb = JsonbBuilder.create();
    }

    public String convertToJson(Object obj) throws ObjectMappingException {
        return jsonb.toJson(obj);
    }

    public Object convertFromJson(String json, Class<?> outClass) throws ObjectMappingException {
        return jsonb.fromJson(json, outClass);
    }

    //Rest of implementation if any

}

class App () {

    public App() {
        var customMapper = new VerySimpleCustomMapper();
        var restClient = new RestJsonClient(customMapper);
    }
}

The ObjectMappingException should be thrown in case the serialization/desiralization implementation fails.

Responses

The RestJsonClient methods get, post, put, patch, delete return instances of MappedResponse while head returns instance of NoBodyResponse like the regular RestClient

The MappedResponse is Java Record that contains the body, response code and response headers:

record MappedResponse(int code, Map<String, List<String>> headers, Object body)

Using the AsyncRestClient (Non-Blocking)

In case you need simple Rest Client in a reactive code to call Rest API, then the AsyncRestClient is what you need. It is build on top of Java CompletableFuture. To keep consistency, the API is the same as the RestClient with the only difference being the responses being a CompletableFuture

Making requests

Here is an example how to do a simple GET request with the AsyncRestClient:

var asyncRestClient = new AsyncRestClient();
asyncRestClient.get("https://example.com/rest/endpoint");

Here is an example how to do a simple POST request with the AsyncRestClient:

var asyncRestClient = new AsyncRestClient();
var reqBody = "{\"test\": 1}";
asyncRestClient.post("https://example.com/rest/endpoint", reqBody);

Constructor

The default constructor creates an instance of the AsyncRestClient with common defaults: HTTP v1.1, No redirect from Https to Http, 30 Seconds timeout, UTF-8 charset and Content-Type: application/json header. You can overwrite, add new or remove headers that the AsyncRestClient is sending:

var asyncRestClient = new AsyncRestClient();
// We overwrite the Content-Type
asyncRestClient.addHeader("Content-Type", "text/plain");
// We add new header
asyncRestClient.addHeader("CustomHeader", "ExampleValue");
// We send an request
asyncRestClient.get("https://example.com/plain/text");
// We remove the custom header
asyncRestClient.removeHeader("CustomHeader");

In case the defaults don't suite your needs you can create instances of the AsyncRestClient with custom setting:

var customHeaders = Map.of("Content-Type", "application/json", "CustomName", "CustomValue");
var asyncRestClient = new AsyncRestClient(HttpClient.Version.HTTP_2, HttpClient.Redirect.ALWAYS, Duration.ofSeconds(10), customSslContect, customHeaders, StandardCharsets.ISO_8859_1);

Responses

The AsyncRestClient methods get, post, put, patch, delete return instances of CompletableFuture while head returns instance of CompletableFuture

Using the AsyncRestJsonClient (Non-Blocking)

RequestHelper class

The RequestHelper class provides method for common uses cases

Authenication/Authorization

Currently the helper can build Basic Authorization and Bearer token header values:

var basicAuthorizationValue = RequestHelper.buildBasicAuthHeader("user", "password");

var restClient = new RestClient();
restClient.addHeader("Authorization", basicAuthorizationValue);

//or

var bearerTokenValue = RequestHelper.buildBearerHeader("token");
restClient.addHeader("Authorization", bearerTokenValue);

About

jHttpClient is opensource under the Apache Software Licence 2.0 If you want to report an issue, you can do it at https://github.com/NestigoGroup/jhttpclient