What it is
Apache HttpComponents is a set of Java libraries for client-side and server-side HTTP communication. The most commonly used module is HttpClient, which provides a robust and flexible API for sending HTTP requests and handling responses.
HttpComponents HttpClient allows you to send HTTP requests (GET, POST, PUT, DELETE, etc.), handle headers, cookies, authentication, and manage connection pooling. It supports synchronous and asynchronous operations and integrates easily with Java applications.
Installation
Add dependency in pom.xml:
<dependency>
<groupId>org.apache.httpcomponents.client5</groupId>
<artifactId>httpclient5</artifactId>
<version>5.3.1</version>
</dependency>Getting started
The smallest useful thing you can do with it, and what each part means.
import org.apache.hc.client5.http.fluent.Request;
String response = Request.get("https://httpbin.org/get").execute().returnContent().asString();
System.out.println(response);import org.apache.hc.client5.http.fluent.Request;
import org.apache.hc.core5.http.ContentType;
String json = "{\"key\":\"value\"}";
String response = Request.post("https://httpbin.org/post")
.bodyString(json, ContentType.APPLICATION_JSON)
.execute().returnContent().asString();
System.out.println(response);Advanced usage
Where the library earns its place over a simpler alternative.
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.client5.http.classic.methods.HttpGet;
import org.apache.hc.core5.http.io.entity.EntityUtils;
CloseableHttpClient client = HttpClients.custom().build();
HttpGet request = new HttpGet("https://httpbin.org/headers");
request.addHeader("Authorization", "Bearer TOKEN");
String response = client.execute(request, httpResponse -> EntityUtils.toString(httpResponse.getEntity()));
System.out.println(response);import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
cm.setMaxTotal(100);
cm.setDefaultMaxPerRoute(20);
CloseableHttpClient client = HttpClients.custom().setConnectionManager(cm).build();import org.apache.hc.client5.http.config.RequestConfig;
RequestConfig config = RequestConfig.custom()
.setConnectTimeout(5000)
.setResponseTimeout(5000)
.build();
HttpGet request = new HttpGet("https://httpbin.org/delay/10");
request.setConfig(config);import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
import org.apache.hc.client5.http.impl.async.HttpAsyncClients;
import org.apache.hc.client5.http.async.methods.SimpleHttpRequest;
import java.util.concurrent.Future;
CloseableHttpAsyncClient asyncClient = HttpAsyncClients.createDefault();
asyncClient.start();
Future response = asyncClient.execute(SimpleHttpRequest.create("GET", "https://httpbin.org/get"), null);
System.out.println(response.get());Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- IOException
- Occurs due to network issues or unreachable endpoints. Check connectivity and URLs.
- HttpResponseException
- Thrown when the server responds with an unexpected HTTP status code. Handle response codes appropriately.
- ConnectionPoolTimeoutException
- Occurs when connection pool is exhausted. Increase pool size or reuse clients efficiently.
Best practices
- Reuse HttpClient instances to take advantage of connection pooling.
- Always close responses and clients to avoid resource leaks.
- Set appropriate timeouts to prevent blocking in network failures.
- Handle exceptions like IOException, HttpException to manage request failures.
- Use asynchronous clients for scalable, non-blocking HTTP requests.
Background
Why it exists, and what it was reacting to.
HttpComponents was developed by the Apache Software Foundation to provide a reliable and extensible HTTP client and server implementation for Java. It is widely used for interacting with REST APIs, web scraping, and performing network requests with fine-grained control over connections, cookies, and authentication.