Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

The Java HttpClient API was introduced with Java 11. The API implements the client-side of the most recent HTTP standards. It supports HTTP/1.1 and HTTP/2, both synchronous and asynchronous programming models.

We can use it to send HTTP requests and retrieve their responses. Before Java 11, we had to rely on a rudimentary URLConnection implementation or third-party libraries such as Apache HttpClient.

In this tutorial, we’ll look at the sending POST requests using Java HttpClient. We’ll show how to send both synchronous and asynchronous POST requests, as well as concurrent POST requests. In addition, we’ll check how to add authentication parameters and JSON bodies to POST requests.

Finally, we’ll see how to upload files and submit form data. Therefore, we’ll cover most of the common use cases.

2. Preparing a POST Request

Before we can send an HTTP request, we’ll first need to create an instance of an HttpClient.

HttpClient instances can be configured and created from its builder using the newBuilder method. Otherwise, if no configuration is required, we can make use of the newHttpClient utility method to create a default client:

HttpClient client = HttpClient.newHttpClient();

HttpClient will use HTTP/2 by default. It will also automatically downgrade to HTTP/1.1 if the server doesn’t support HTTP/2.

Now we are ready to create an instance of HttpRequest from its builder. We’ll make use of the client instance to send this request later on. The minimum parameters for a POST request are the server URL, request method, and body:

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create(serviceUrl))
  .POST(HttpRequest.BodyPublishers.noBody())
  .build();

A request body needs to be supplied via the BodyPublisher class. It’s a reactive-stream publisher that publishes streams of request body on-demand. In our example, we used a body publisher which sends no request body.

3. Sending a POST Request

Now that we’ve prepared a POST request, let’s look at the different options for sending it.

3.1. Synchronously

We can send the prepared request using this default send method. This method will block our code until the response has been received:

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString())

The BodyHandlers utility implements various useful handlers, such as handling the response body as a String or streaming the response body to a file. Once the response is received, the HttpResponse object will contain the response status, headers, and body:

assertThat(response.statusCode())
  .isEqualTo(200);
assertThat(response.body())
  .isEqualTo("{\"message\":\"ok\"}");

3.2. Asynchronously

We could send the same request from the previous example asynchronously using the sendAsync method. Instead of blocking our code, this method will immediately return a CompletableFuture instance:

CompletableFuture<HttpResponse<String>> futureResponse = client.sendAsync(request, HttpResponse.BodyHandlers.ofString());

The CompletableFuture completes with the HttpResponse once it becomes available:

HttpResponse<String> response = futureResponse.get();
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.body()).isEqualTo("{\"message\":\"ok\"}");

3.3. Concurrently

We can combine Streams with CompletableFutures in order to issue several requests concurrently and await their responses:

List<CompletableFuture<HttpResponse<String>>> completableFutures = serviceUrls.stream()
  .map(URI::create)
  .map(HttpRequest::newBuilder)
  .map(builder -> builder.POST(HttpRequest.BodyPublishers.noBody()))
  .map(HttpRequest.Builder::build)
  .map(request -> client.sendAsync(request, HttpResponse.BodyHandlers.ofString()))
  .collect(Collectors.toList());

Now, let’s wait for all the requests to be complete so that we can process their responses all at once:

CompletableFuture<List<HttpResponse<String>>> combinedFutures = CompletableFuture
  .allOf(completableFutures.toArray(new CompletableFuture[0]))
  .thenApply(future ->
    completableFutures.stream()
      .map(CompletableFuture::join)
      .collect(Collectors.toList()));

As we’ve combined all the responses using the allOf and join methods, we get a new CompletableFuture that holds our responses:

List<HttpResponse<String>> responses = combinedFutures.get();
responses.forEach((response) -> {
  assertThat(response.statusCode()).isEqualTo(200);
  assertThat(response.body()).isEqualTo("{\"message\":\"ok\"}");
});

4. Adding Authentication Parameters

We can set an authenticator on the client level for HTTP authentication on all requests:

HttpClient client = HttpClient.newBuilder()
  .authenticator(new Authenticator() {
    @Override
    protected PasswordAuthentication getPasswordAuthentication() {
      return new PasswordAuthentication(
        "baeldung",
        "123456".toCharArray());
      }
  })
  .build();

However, the HttpClient does not send basic credentials until challenged for them with a WWW-Authenticate header from the server.

To bypass this, we can always create and send the basic authorization header manually:

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create(serviceUrl))
  .POST(HttpRequest.BodyPublishers.noBody())
  .header("Authorization", "Basic " + 
    Base64.getEncoder().encodeToString(("baeldung:123456").getBytes()))
  .build();

5. Adding a Body

In the examples so far, we haven’t added any bodies to our POST requests. However, the POST method is commonly used to send data to the server via the request body.

5.1. JSON Body

The BodyPublishers utility implements various useful publishers, such as publishing the request body from a String or a file. We can publish JSON data as String, converted using the UTF-8 character set:

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create(serviceUrl))
  .POST(HttpRequest.BodyPublishers.ofString("{\"action\":\"hello\"}"))
  .build();

5.2. Uploading Files

Let’s create a temporary file that we can use for uploading via HttpClient:

Path file = tempDir.resolve("temp.txt");
List<String> lines = Arrays.asList("1", "2", "3");
Files.write(file, lines);

HttpClient provides a separate method, BodyPublishers.ofFile, for adding a file to the POST body. We can simply add our temporary file as a method parameter, and the API takes care of the rest:

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create(serviceUrl))
  .POST(HttpRequest.BodyPublishers.ofFile(file))
  .build();

5.3. Submitting Forms

Contrary to files, HttpClient does not provide a separate method for posting form data. Therefore, we’ll again need to make use of the BodyPublishers.ofString method:

Map<String, String> formData = new HashMap<>();
formData.put("username", "baeldung");
formData.put("message", "hello");

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create(serviceUrl))
  .header("Content-Type", "application/x-www-form-urlencoded")
  .POST(HttpRequest.BodyPublishers.ofString(getFormDataAsString(formData)))
  .build();

However, we’ll need to convert the form data from a Map to a String using a custom implementation:

private static String getFormDataAsString(Map<String, String> formData) {
    StringBuilder formBodyBuilder = new StringBuilder();
    for (Map.Entry<String, String> singleEntry : formData.entrySet()) {
        if (formBodyBuilder.length() > 0) {
            formBodyBuilder.append("&");
        }
        formBodyBuilder.append(URLEncoder.encode(singleEntry.getKey(), StandardCharsets.UTF_8));
        formBodyBuilder.append("=");
        formBodyBuilder.append(URLEncoder.encode(singleEntry.getValue(), StandardCharsets.UTF_8));
    }
    return formBodyBuilder.toString();
}

6. Conclusion

In this article, we explored sending POST requests using Java HttpClient API introduced in Java 11.

We learned how to create an HttpClient instance and prepare a POST request. We saw how to send prepared requests synchronously, asynchronously, and concurrently. Next, we also saw how to add basic authentication parameters.

Finally, we looked at adding a body to a POST request. We covered JSON payloads, uploading files, and submitting form data.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW