Java HttpClient

java.net.http.HttpClient, standardised in Java 11, is the modern HTTP API and the one to reach for in new code. It replaces the verbose HttpURLConnection with an immutable, builder-based design: HTTP/2 by default, native synchronous and asynchronous calls, and pluggable handling of request and response bodies. Three types do the work — HttpClient, HttpRequest, and HttpResponse.

The three types

HttpClient client = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_2)       // HTTP/2, falling back to 1.1
        .connectTimeout(Duration.ofSeconds(10))
        .followRedirects(HttpClient.Redirect.NORMAL)
        .build();

A single HttpClient is thread-safe and reusable — build one and share it across the whole application; do not create one per request. From it you send HttpRequest objects and get back HttpResponse objects.

Building a request

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://example.com/api"))
        .header("Accept", "application/json")
        .timeout(Duration.ofSeconds(5))
        .POST(HttpRequest.BodyPublishers.ofString("{\"x\":1}"))
        .build();

The verb method (GET(), POST(...), PUT(...), DELETE()) is chosen on the builder. A BodyPublisher supplies the request body — ofString, ofByteArray, ofFile, or noBody(). Requests are immutable once built and can be reused.

Sending: synchronous and asynchronous

// Blocking
HttpResponse<String> resp =
        client.send(request, HttpResponse.BodyHandlers.ofString());

// Non-blocking — returns a CompletableFuture
CompletableFuture<HttpResponse<String>> future =
        client.sendAsync(request, HttpResponse.BodyHandlers.ofString());

A BodyHandler decides how the response body is materialised: ofString(), ofByteArray(), ofFile(path), ofLines() (a Stream<String>), or discarding(). sendAsync returns a CompletableFuture, so you chain .thenApply, .thenAccept, and .exceptionally without blocking a thread.

A worked example: sync GET, sync POST, and async

This program serves a loopback endpoint that reports the HTTP method it received, then drives it three ways with one shared HttpClient: a synchronous GET, a synchronous POST with a body, and an asynchronous GET through a CompletableFuture.

java— editable, runs on the server

import com.sun.net.httpserver.HttpServer;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.concurrent.CompletableFuture;

public class HttpClientDemo {
  public static void main(String[] args) throws Exception {
    HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
    server.createContext("/api", ex -> {
      byte[] body = ("handled " + ex.getRequestMethod()).getBytes(StandardCharsets.UTF_8);
      ex.sendResponseHeaders(200, body.length);
      try (OutputStream os = ex.getResponseBody()) { os.write(body); }
    });
    server.start();
    int port = server.getAddress().getPort();
    URI uri = URI.create("http://127.0.0.1:" + port + "/api");

// ONE client, reused for every request
    HttpClient client = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(2))
        .build();

// 1. Synchronous GET
    HttpRequest get = HttpRequest.newBuilder(uri).GET().build();
    HttpResponse<String> r1 = client.send(get, HttpResponse.BodyHandlers.ofString());
    System.out.println("sync GET  -> " + r1.statusCode() + " / " + r1.body());

// 2. Synchronous POST with a request body
    HttpRequest post = HttpRequest.newBuilder(uri)
        .header("Content-Type", "text/plain")
        .POST(HttpRequest.BodyPublishers.ofString("payload"))
        .build();
    HttpResponse<String> r2 = client.send(post, HttpResponse.BodyHandlers.ofString());
    System.out.println("sync POST -> " + r2.statusCode() + " / " + r2.body());

// 3. Asynchronous GET returning a CompletableFuture
    CompletableFuture<String> future = client
        .sendAsync(get, HttpResponse.BodyHandlers.ofString())
        .thenApply(HttpResponse::body)
        .thenApply(b -> "async GET -> " + b);
    System.out.println(future.get());   // join the async result

server.stop(0);
  }
}

What to take from the run:

One HttpClient served all three requests. The client is immutable and thread-safe, so the right pattern is build-once-share-everywhere; spinning up a client per call wastes connection pools and HTTP/2 sessions. Notice no disconnect() anywhere — the client manages connections for you.
The request verb lived on the builder: .GET() for the read and .POST(BodyPublishers.ofString("payload")) for the write. The server echoed back the method it saw (handled GET, handled POST), confirming the publisher both carried the body and set the verb.
HttpResponse is a typed object with statusCode() and body(). Because a BodyHandlers.ofString() was passed, the body came back already decoded as a String — swap in ofByteArray, ofFile, or ofLines and the same call yields bytes, a saved file, or a stream of lines.
The asynchronous call returned a CompletableFuture and composed with .thenApply without blocking a thread until future.get(). That is the structural win over HttpURLConnection: concurrency is built in, so hundreds of in-flight requests need not mean hundreds of parked threads.
The whole flow — client, request, sync and async sends, typed responses — used no manual streams and no error-stream trap. Compared with the previous chapter, HttpClient is shorter, safer, and more capable, which is why it is the default choice on Java 11+.

Practice

In a high-traffic service, a developer writes 'HttpClient.newHttpClient()' inside the method that handles each incoming request, creating a fresh client per call. Reviewers flag it. Why?

'HttpClient' is immutable and thread-safe and pools connections; you should build one and reuse it, since a client per request discards connection reuse and HTTP/2 sessions
'HttpClient.newHttpClient()' throws if called more than once per JVM, so the second request will fail
A new client per request is required because 'HttpClient' is not thread-safe and cannot be shared
It is fine and even recommended, because each client must be closed with 'disconnect()' after a single request