Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 119 ยท Web Fundamentals

Calling APIs with HttpClient

Call REST APIs from Java with java.net.http.HttpClient - GET, POST, PUT and DELETE with JSON via Jackson, headers, timeouts, async calls, errors and retries.

Sooner or later every backend calls another service: a payment provider, a weather API, the inventory service next door. Since Java 11 the JDK has a modern HTTP client built in, java.net.http.HttpClient. It speaks HTTP/1.1 and HTTP/2, supports synchronous and asynchronous calls, and needs no extra library. Spring's RestClient and many SDKs can use it under the hood, so learning it well pays off everywhere.

Calling an API correctly takes more than one line, though. You need to send and parse JSON, set timeouts so a slow server can't freeze your application, check status codes (the client doesn't throw on 404 or 500), run independent calls in parallel, and retry failures without making things worse. This lesson covers all of it. Every example starts a small local server with com.sun.net.httpserver.HttpServer in the same program, so you see both sides. If request lines, status codes and headers are new, start with How HTTP Works.

The three building blocks

The API has three main types:

  • HttpClient: holds configuration (timeouts, redirects, HTTP version, cookies, proxy, executor) and a connection pool. It is immutable and thread-safe. Create one and reuse it; building a new client per request throws away pooled connections.
  • HttpRequest: one immutable request: URI, method, headers, body publisher and timeout. Built with HttpRequest.newBuilder().
  • HttpResponse<T>: the status code, headers, final URI and a body of type T. The BodyHandler you pass to send decides what T is.
Java
HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(2))           // limit for opening the TCP connection
    .followRedirects(HttpClient.Redirect.NORMAL)     // follow redirects, but never https -> http
    .build();

HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.example.com/books?author=le+guin"))
    .header("Accept", "application/json")
    .timeout(Duration.ofSeconds(5))                  // limit for this request until the headers arrive
    .GET()
    .build();

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

HttpClient implements AutoCloseable since Java 21. In a long-running application you keep one client for the application's lifetime; in short programs like the examples here, try-with-resources closes it cleanly.

The first example shows the common body handlers, query parameters with proper encoding, and what happens with a redirect.

Java Requests, body handlers and redirects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

URLEncoder turned the spaces into +, the & into %26 and the accented letters into UTF-8 bytes like %C3%A9, and the server decoded it back with URLDecoder. (The server reads getRawQuery() on purpose: URI.getQuery() decodes %26 to & but leaves + alone, which garbles form-encoded values.) Without encoding, the & would have split the value into a second parameter. The default redirect policy is NEVER, so without followRedirects(NORMAL) you would have received the 301 itself.

Other body handlers you will use: ofByteArray() for binary data, ofInputStream() for large downloads you process as a stream, and ofFile(path) to save straight to disk. On the request side, BodyPublishers.ofString, ofByteArray, ofFile and noBody() cover almost every case.

JSON requests and responses with Jackson

The JDK has no JSON library, so pair HttpClient with Jackson (see JSON with Jackson). Sending JSON means: serialize to a string, set Content-Type: application/json, and use BodyPublishers.ofString. Receiving JSON means reading the body and calling readValue.

You can go one step further and write a reusable BodyHandler that converts the body while it is received. BodySubscribers.mapping wraps an existing subscriber with a conversion function. The handler below checks the status code first, so error responses don't get parsed as if they were data.

Java A JSON CRUD client with Jackson

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Three things deserve attention:

  • TypeReference<List<Todo>> keeps the generic type at runtime, so Jackson builds a List<Todo> instead of a list of maps.
  • The 404 for /todos/99 came back as a normal response, and only our handler turned it into an error. When a body handler's conversion throws, send wraps the failure in an IOException, which is why the example reads e.getCause().
  • HttpRequest.Builder.method(name, publisher) works for any method. The shortcuts GET(), POST(...), PUT(...) and DELETE() are just convenience.

HttpClient never throws on HTTP error statuses. A 500 with an HTML error page is a perfectly successful send. Always check statusCode() (or use a handler like the one above) before you trust the body. Exceptions mean the exchange itself failed: no connection, a timeout, a reset.

Headers and authentication

Add headers with .header(name, value) (appends) or .setHeader(name, value) (replaces). Most APIs authenticate with a token in the Authorization header:

Java
HttpRequest request = HttpRequest.newBuilder(uri)
    .header("Authorization", "Bearer " + System.getenv("API_TOKEN"))
    .header("Accept", "application/json")
    .header("Request-Id", UUID.randomUUID().toString())   // helps correlate logs across services
    .build();

A few headers are restricted because the client manages them itself: Host, Connection, Content-Length, Expect and Upgrade. Setting them throws IllegalArgumentException. For HTTP Basic authentication, you can either set Authorization: Basic <base64(user:password)> yourself or configure an Authenticator on the client builder, which answers 401 challenges automatically. Never hard-code secrets in source code; read them from the environment or a secret store.

Timeouts: never wait forever

A call without a timeout is a bug waiting for a slow day. If the remote service hangs, every thread that calls it hangs too, and soon your own service stops responding. HttpClient has two separate limits:

  • connectTimeout on the client: how long to wait for the TCP (and TLS) connection.
  • timeout on the request: how long to wait until the response headers arrive. If it expires, send throws HttpTimeoutException.

There is no default for either: without them, a request can wait indefinitely.

Java A request timeout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The server needs 800 ms. With a 300 ms limit the client gives up after about 300 ms; with 1,500 ms it gets the answer. Choose timeouts from the remote service's real latency (for example a bit above its 99th percentile) and from how long your caller is willing to wait. A user-facing request that calls three services in a row can't give each of them 30 seconds.

The request timeout only covers the time until the headers arrive. If you stream a huge body with ofInputStream(), reading it can take longer, and you need your own limit for that part.

Asynchronous and parallel calls

sendAsync returns a CompletableFuture<HttpResponse<T>> immediately and completes it when the response arrives. That makes independent calls easy to run in parallel: start them all, then wait for all of them. The CompletableFuture lesson covers the composition methods in depth.

Java Sequential versus parallel calls with sendAsync

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Five calls of about 200 ms each take more than a second one after another (the first call also pays for opening the connection), but only a little over 200 ms in parallel. Two practical notes:

  • Parallel calls need a server that handles them in parallel. The HttpServer here uses a virtual-thread executor; with its default single thread, the "parallel" requests would queue up on the server side.
  • Virtual threads are the simpler alternative. On Java 21+, you can keep the readable blocking send and run each call in its own virtual thread (Executors.newVirtualThreadPerTaskExecutor()). The result is just as fast and the stack traces are much easier to read. See Virtual Threads and Structured Concurrency. Use sendAsync when you already work with futures, or when you need to combine and transform results as they arrive.

With futures, handle failures in the chain: .exceptionally(e -> fallback) or .handle((value, error) -> ...). If you only join(), a failed call throws CompletionException wrapping the real cause.

Error handling and retries

Things that go wrong when calling an API fall into three groups, and each needs a different reaction:

What happened How it shows up Retry?
Can't connect, connection reset ConnectException, IOException Yes, with backoff (if the request is idempotent)
Too slow HttpTimeoutException Maybe, once; the server may still be processing it
Server overloaded or temporarily down 503, 502, 504, 429 (often with Retry-After) Yes, with backoff
Bad request, not found, no permission 400, 401, 403, 404, 409, 422 No: the same request will fail again
Server bug 500 Usually no, or at most once

Retrying is safe only for idempotent operations (GET, PUT, DELETE), or for POSTs that carry an idempotency key the server deduplicates (see REST API Design). Otherwise a retry after a timeout can charge a customer twice. And always use exponential backoff with jitter: wait 100 ms, then 200 ms, then 400 ms, each with some randomness, so a thousand clients don't hammer a recovering server at the same instant.

Java Retries with backoff and Retry-After

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The flaky endpoint succeeds on the third attempt. The 404 fails immediately, because retrying a missing resource is pointless. When the server is down, each attempt fails with ConnectException until the helper gives up. In production you would add a total time budget, log each retry, and usually reach for a library such as Resilience4j, which also adds circuit breakers: after many failures, stop calling the broken service for a while and fail fast. The Microservices lesson builds one.

Production checklist

  • One shared HttpClient per application (or per remote service if their settings differ).
  • connectTimeout on the client and timeout on every request.
  • Check the status code on every response; map errors to meaningful exceptions.
  • Retry only idempotent requests, only on retryable failures, with exponential backoff, jitter and a maximum.
  • Encode query parameters with URLEncoder; build paths from trusted pieces.
  • Send Accept and Content-Type; pass a request ID header for tracing.
  • Keep secrets out of URLs (they end up in logs) and out of source code.
  • Log the method, URL without secrets, status and duration for every call.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. client.send(request, BodyHandlers.ofString()) gets a 500 response. What happens?

    HttpClient treats any complete HTTP response as a success. It is your code's job to check the status code.
  2. 2. Why should you create one HttpClient and reuse it?

    HttpClient is immutable, thread-safe and pools connections. Creating one per request throws all of that away.
  3. 3. Which failure should a retry helper NOT retry?

    A 404 will be the same on the next attempt. 503, 429 and connection failures are typically temporary.
  4. 4. In the parallel example, what would happen if the server used HttpServer's default executor?

    The default HttpServer executor runs handlers on a single thread. The client sends all requests at once, but the server processes them one after another.
  5. 5. What does the request timeout(Duration.ofSeconds(2)) limit?

    The request timeout covers the wait for the response (headers). Use connectTimeout for connecting, and your own limit when streaming a long body.

Summary

  • HttpClient (configuration and connection pool, thread-safe, reuse it), HttpRequest (immutable, built with a builder) and HttpResponse<T> (body type chosen by a BodyHandler) are the core types.
  • Body handlers: ofString, ofLines, ofByteArray, ofInputStream, ofFile, discarding; publishers: ofString, ofByteArray, ofFile, noBody.
  • For JSON, combine Jackson with BodyPublishers.ofString and a custom handler built on BodySubscribers.mapping; use TypeReference for generic types.
  • Error statuses are not exceptions. Exceptions mean the exchange failed: connection problems or HttpTimeoutException.
  • Always set connectTimeout and a per-request timeout.
  • sendAsync plus CompletableFuture.allOf runs independent calls in parallel; virtual threads with blocking send are an equally fast, simpler option.
  • Retry only idempotent requests on temporary failures (connection errors, 429, 502โ€“504), with exponential backoff, jitter, a limit and respect for Retry-After.

Next: Building a REST API with the JDK switches sides and builds a complete JSON CRUD API on HttpServer.