Skip to content
Enhancing/simplify apache http client
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.


This lib is built on apache http client for sending rest requests.

Main purpose of the http-request, create simple rest client quickly, manage your response very simple and don't worry about Exceptions.

http-request Features: Building your HttpRequest requires no more than 5 minutes.
Used builder pattern to create HttpRequest.
HttpRequest is designed as one instance to one URI.
HttpRequest is immutable (thread safe after build).
There are overloaded methods of execute() for sending request.
All exceptions are wrapped:
If connection failure -> status code is a 503(SC_SERVICE_UNAVAILABLE), If deserialization of response body is failed -> status code is a 502(SC_BAD_GATEWAY).
After request ResponseHandler instance is provided to manipulate response data.

  • converting response to the type which you want.
  • ignore response body if you interested in only status code.
  • converting from Json.
  • converting from Xml.
    Optimized performance.

Full API documentation is available here.

Note: HttpRequest objects are immutable and thread-safe, they should be reused after build the instance of HttpRequest.

How to use

Retrieve the Status Code from the Http Response After sending the Http request – we get back an instance of com.jsunsoft.http.ResponseHandler –
which allows us to access the status line of the response, and implicitly the Status Code:

HttpRequest<?> httpRequest = HttpRequestBuilder.createGet("").build();
ResponseHandler responseHandler = httpRequest.execute();
int statusCode = responseHandler.getStatusCode();

Building HttpRequest by default options

HttpRequest<SomeTypeToConvertResponseBody> httpRequest = HttpRequestBuilder.createGet(uriString,  SomeTypeToConvertResponseBody.class).build();

If you want to ignore the convert of response body, you must build it so:

HttpRequest<?> httpRequest = HttpRequestBuilder.createGet(uri).build();

If you want to convert response body to Generic class (example List) by some type you must build it so:

HttpRequest<List<SomeType>> httpRequest = HttpRequestBuilder.createGet(uri,  new TypeReference<List<SomeType>>(){}).build();
ResponseHandler<List<SomeType>> responseHandler = httpRequest.execute();

List<SomeType> someTypes = responseHandler.get(); //see javadoc of get method
List<SomeType> someTypes = responseHandler.orElse(Collections.emptyList());

If you want to convert response body with custom way you must add custom deserializer:

HttpRequest httpRequest = HttpRequestBuilder.createGet(uriString, SomeTypeToConvertResponseBody.class) .responseDeserializer(responseContext -> //deserialize yourself) .build(); //See the javadoc of methods of ResponseContext

Perform simple http request Perform request and get the body of the response as String

HttpRequest<String> httpRequest = HttpRequestBuilder.create(someHttpMethod, "", String.class)
String responseBody = httpRequest.execute().get(); // see javadoc of get method

Perform simple http get request

HttpRequest<String> httpRequest = HttpRequestBuilder.createGet("", String.class)
String responseBody = httpRequest.execute(requestParameters).get(); // see documentation of get method
String responseBody = httpRequest.executeWithQuery(queryString).get(); // //queryString example "param1=param1&param2=param2"

Perform simple http post request

HttpRequest<String> httpRequest = HttpRequestBuilder.createPost("", String.class)
String responseBody = httpRequest.execute(requestParameters).get(); // see javadoc of get method

Build HttpRequest and add HEADERS which should be send always.

HttpRequestBuilder.create(HttpMethod.PUT, "").addDefaultHeader(someHeader).build();
HttpRequestBuilder.create(HttpMethod.PUT, "").addDefaultHeaders(someHeaderCollection).build();
HttpRequestBuilder.create(HttpMethod.PUT, "").addDefaultHeaders(someHeaderArray).build();
HttpRequestBuilder.create(HttpMethod.PUT, "").addDefaultHeader(headerName, headerValue).build();

Configure connection pool By default connection pool size of apache http client is 2. I changed the parameter to default value to 128. To set custom value you can:

HttpRequestBuilder.create(someHttpMethod, someUri).maxPoolPerRoute(someIntValue).build();
ConnectionConfig connectionConfigInstance = ConnectionConfig.create().maxPoolPerRoute(someIntValue);
HttpRequestBuilder.create(someHttpMethod, someUri).connectionConfig(connectionConfigInstance).build();

How to set proxy

HttpRequest httpRequest = HttpRequestBuilder.create(someHttpMethod, someUri).proxy(host, port).build();


socketTimeOut is 30000ms
connectionRequestTimeout is 30000ms
connectTimeout is 5000ms;

For more information see ( or (

To change default timeouts you can:

HttpRequestBuilder.create(someHttpMethod, someUri)

Following redirects

By default redirecting are disabled. to enable you can:

or set custom redirect strategy

Ignore SSL certificate

HttpRequest<?> httpRequest = HttpRequestBuilder.createGet("")
            .addDefaultHeader("accept", "application/json")

int statusCode = httpRequest.execute().getStatusCode(); // 200

Basic Authentication

            .basicAuth("username_admin", "secret_password").build();

int statusCode = httpRequest.execute().getStatusCode(); //200

Customize CloseableHttpClient before the http-request is built

                .addHttpClientCustomizer(httpClientBuilder -> /* here you can customize your client*/)

For example if you want to add the Keep-Alive:

                .addHttpClientCustomizer(httpClientBuilder -> httpClientBuilder.setKeepAliveStrategy((response, context) -> {
                    //your code;

Real world example how http-request simple and useful.

No try/catch, No if/else

import com.jsunsoft.http.*;
import java.util.List;
import org.apache.http.entity.ContentType;

public class Rest{
    private static final HttpRequest<List<String>> httpRequest =
     HttpRequestBuilder.createGet("", new TypeReference<java.util.List<String>>() {})
     public void send(String jsonData){
     private void whenSuccess(ResponseHandler<List<String>> responseHandler){
         //When predicate of filter returns true, calls whenHasContent else calls whenHasNotContent
     private void whenNotSuccess(ResponseHandler<List<String>> responseHandler){
         //For demo. You can handle what you want
          System.err.println("Error code: " + responseHandler.getStatusCode() + ", error message: " + responseHandler.getErrorText());
     private void whenHasContent(ResponseHandler<List<String>> responseHandler){
         //For demo. 
         List<String> responseBody = responseHandler.get();
     private void whenHasNotContent(ResponseHandler<List<String>> responseHandler){
         //For demo. 
           System.out.println("Response is success but body is missing. Response code: " + responseHandler.getStatusCode());

To use from maven add this snippet to the pom.xml dependencies section:


Pull requests are welcome.

You can’t perform that action at this time.