Java HTTP Client API

A built-in Java API for making HTTP requests and handling responses. Introduced in modern Java (standardized in Java 11), it replaces older low-level APIs with cleaner synchronous and asynchronous programming. HttpClient, HttpRequest, HttpResponse.

Cleaner API, async support, HTTP/2 support. It provides modern request building, futures-based async calls, and better readability for production networking code. client.sendAsync(…) with CompletableFuture.

HttpClient, HttpRequest, HttpResponse. Client configures behavior, request defines outbound call, response holds status/headers/body. build request once, send via client.

HttpClient is designed for reuse and concurrent use. Create and reuse one configured client instance for many requests. singleton client bean in app service layer.

HTTP/1.1 and HTTP/2. HTTP/2 can reduce latency via multiplexing on one connection where supported. API gateway endpoints often support HTTP/2.

Defines how response body is consumed. Choose string, byte array, file, stream, or custom processing based on payload size/use. BodyHandlers.ofString() for JSON payload.

Defines how request body is sent. Can send strings, byte arrays, files, or streams for POST/PUT/PATCH requests. BodyPublishers.ofString(json).

Usually no. Reuse improves connection pooling and performance consistency. static final/shared client instance.

Java 11+. API matured and is widely used in modern Java backend projects. Java 21 apps commonly use it.

Build request -> send -> inspect status/body/headers. Robust code also handles timeout, retry policy, and error mapping. status 2xx success, 4xx/5xx mapped to domain errors.

Use HttpRequest builder with URI and GET. Request object is immutable after build, good for predictable behavior.

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/users"))
    .GET()
    .build();

Include them in URI. Properly encode user input to avoid malformed URLs and injection-like issues. /search?q=java&page=1

.header(name, value) or .headers(…). Use headers for auth, content negotiation, tracing, idempotency keys. Authorization: Bearer …

POST + BodyPublisher + content-type header. Always set Content-Type: application/json for JSON request payloads.

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/orders"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

Use .PUT(…) and .DELETE(). Respect API semantics: PUT often idempotent replace/update, DELETE remove resource. update profile with PUT.

Yes, via request builder .timeout(…). Per-request timeout helps tune critical endpoints differently. profile API 300ms, reporting API 2s.

Configure at client/request level. Default is usually fine, but explicit version can help compatibility/performance testing. HttpClient.Version.HTTP₂

Helps observability and provider-side diagnostics. External APIs often request identifiable client metadata for support/debugging. User-Agent: my-service/1.2.0

Encode body and set form content type. Use application/x-www-form-urlencoded with proper URL encoding. grant_type=client_credentials…

Missing timeout and missing content-type. Leads to hanging calls and server misinterpretation of body. POST JSON without content-type header.

Status code, headers, body, request metadata. Always validate status and parse body according to response contract. response.statusCode().

Use BodyHandlers.ofString(). Best for typical JSON/text payload sizes.

HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());

Use BodyHandlers.ofByteArray(). Good for binary payloads like files/images/protobuf. file download metadata + raw bytes.

Use BodyHandlers.ofInputStream(). Important for large responses to avoid loading everything into memory. process big CSV stream line by line.

BodyHandlers.ofFile(path). Efficient for downloads and avoids extra memory copies. download report zip to temp path.

Usually treat all 2xx as success (based on API contract). Some APIs use 201/202/204 meaningfully. 204 No Content on successful delete.

response.headers().firstValue("Header-Name"). Useful for rate limits, pagination links, trace IDs. X-RateLimit-Remaining.

Handle gracefully, especially for 204 responses. Don’t always assume JSON body exists. DELETE may return no content.

Prevent parsing wrong payload format. Some error pages return HTML; blindly JSON-parsing causes confusing failures. check Content-Type before Jackson parse.

Check status + headers + body contract together. Robust clients validate the full protocol response, not just body text. 200 with malformed content-type should still be treated suspiciously.

Blocking call using client.send(…). Simpler control flow, good for straightforward logic where blocking is acceptable. backend batch job step.

Non-blocking call using client.sendAsync(…). Returns CompletableFuture, enabling composition and parallel calls. fetch profile and permissions concurrently.

Use send for simplicity, async for concurrency/latency optimization. Async shines when multiple independent remote calls can be overlapped. fan-out to 3 microservices.

CompletableFuture methods (thenApply/thenCompose/thenCombine). Keep chains non-blocking; avoid premature .join() deep in flow. combine user and order futures.

Wait for all async tasks. Useful for fan-in aggregation response patterns. gather data from multiple providers.

Complete when first task finishes. Good for fastest-mirror strategies. query multiple replicas and take first successful.

exceptionally, handle, whenComplete. Choose fallback vs transformation vs side-effect logging intentionally. fallback empty list on recommendation API failure.

It defeats async benefits. Blocking consumes threads and can increase tail latency under load. call join() only at boundary if needed.

CompletableFuture supports cancellation. Useful when parent request times out or client disconnects. cancel downstream calls on request deadline exceeded.

Compose non-blocking, timeout early, handle failures explicitly. Async without deadlines/error strategy creates hidden reliability risks. sendAsync + orTimeout + fallback.

Prevent hanging and resource exhaustion. Without timeouts, slow dependencies can consume threads and collapse service responsiveness. set connect + request time budget.

Connect timeout for TCP connection setup; request timeout for full request processing. Both matter for robust latency control. connect 1s, request 2s.

Configure on HttpClient builder. Controls how long to wait for initial connection establishment.

HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(1))
    .build();

Configure on HttpRequest builder. Enforces per-call max duration aligned to SLA. .timeout(Duration.ofMillis(500))

No. Retry only transient failures (timeouts, 5xx, network glitches) with safe/idempotent operations. retry GET, be careful with POST side effects.

Reduce retry storm and pressure. Spacing retries prevents overload amplification during incidents. 100ms, 200ms, 400ms + jitter.

Avoid synchronized retry spikes. Randomized delay smooths traffic bursts and improves recovery odds. ±20% randomized wait.

Non-idempotent operations can duplicate side effects. Use idempotency keys or safe API design for retried writes. payment POST with idempotency-key header.

Protect system from repeatedly calling failing dependency. Works with timeouts/retries to improve resilience and recovery. open breaker after repeated failures.

Timeouts + retries (careful) + fallback + observability. Reliability is policy-driven, not just API-call syntax. degrade recommendations, keep checkout alive.

Serialize with Jackson, send as String body. Keep serialization config centralized for stable contracts.

String json = mapper.writeValueAsString(dto);
HttpRequest req = HttpRequest.newBuilder(uri)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

Read String body then mapper.readValue. Validate status/content-type before deserialization.

UserDto dto = mapper.readValue(res.body(), UserDto.class);

Depends on API error contract. Many APIs return structured error JSON for 4xx/5xx; parse accordingly. error body {code,message} mapped to ApiErrorDto.

Configure Jackson to ignore unknown when appropriate. Improves forward compatibility with evolving APIs. @JsonIgnoreProperties(ignoreUnknown = true)

Prevent wrong parser assumptions. Error pages/proxies may return HTML/text unexpectedly. reject non-JSON content with clear error.

Type erasure. Use TypeReference for List<T> or generic wrappers. new TypeReference<List<UserDto>>() {}

Usually no. Keep remote contract DTO separate from internal domain to avoid coupling. remote price string mapped into domain Money type.

Impacts update logic and defaults. Distinguish absent vs explicit null for patch semantics. missing field means unchanged, null means clear value.

Assume success body shape without checking status. Leads to parse exceptions hiding real protocol error. 401 HTML parsed as JSON fails confusingly.

Validate protocol first, then parse payload. Correctness starts with status/headers, not mapper call. status check -> content-type check -> readValue.

Authorization header. Rotate tokens safely and avoid logging sensitive headers. Authorization: Bearer <token>

Use Authorization: Basic base64(user:pass) or Authenticator. Prefer HTTPS always; basic auth credentials are only base64 encoded, not encrypted. API legacy integrations.

Validate URI scheme before request. Prevent accidental plaintext transmission of sensitive data. reject http:// in production config.

Yes, with SSLContext/SSLParameters in client builder. Needed for custom trust stores, mTLS, strict cipher/protocol policies. internal service with private CA.

Mutual TLS: both client and server authenticate certificates. Strong service-to-service authentication in zero-trust/internal networks. payment service requires client cert.

Depends on policy. Automatic redirects can be unsafe for auth-sensitive endpoints. avoid forwarding auth to unintended hosts.

Avoid leaking secrets/PII. Headers and payloads may contain tokens, passwords, personal data. mask Authorization and sensitive JSON fields.

Validate/whitelist outbound hosts. Never call arbitrary user-provided URLs directly. allow only approved domains/IP ranges.

Configurable with CookieHandler. Useful for session-based integrations, but token auth is common in APIs. legacy SSO flow.

Secure transport, strict target validation, secret-safe logging. Most client-side incidents come from lax outbound controls. HTTPS + allowlist + redaction.

Yes, when reused properly. Reusing one client enables pooling/keep-alive benefits. singleton client for app lifetime.

Poor pooling and extra overhead. Multiple clients fragment connection reuse and increase resource churn. one per service config, not one per request.

Multiplexing multiple requests over fewer connections. Reduces connection overhead and can improve latency in high-call scenarios. microservice making many calls to same host.

Loads full body into memory. For large payloads prefer streaming/file handlers. large export should use InputStream/file handler.

Usually yes for text/JSON payloads. Saves bandwidth; ensure server/client agree on encoding. Accept-Encoding: gzip

Bound concurrency and use timeouts. Prevent overwhelming downstream and your own resources. semaphore limiting concurrent outbound calls.

Tail latency drives user experience. Averages hide spikes caused by retries/timeouts/contention. p99 jumps during dependency degradation.

latency, success rate, status distribution, timeout/retry counts. Observability enables fast diagnosis and capacity planning. dashboard by downstream service name.

Backpressure control. Unbounded concurrency leads to cascading failures. bounded executor + queue strategy.

Reuse client, bound work, monitor tails. Throughput without control is fragile under real traffic. singleton client + bulkhead + metrics.

Mock wrapper dependencies or use fake transport abstraction. Avoid live network in unit tests for speed/determinism. interface HttpExecutor mocked in service tests.

Use local mock server (e.g., WireMock/MockWebServer). Validates real serialization, headers, status handling, retries. simulate 500 then 200 for retry policy.

Usually no. External instability/rate limits cause flaky builds. keep real API tests as controlled smoke checks only.

Mock server delays response beyond timeout. Assert expected exception/fallback and timing boundaries. delayed endpoint returns timeout path.

Program server to fail first N times then succeed. Assert attempt count and final outcome. verify 3 calls occurred before success.

Assert request headers on mock server. Ensures token propagation logic is correct. recorded request includes Authorization header.

Return malformed/invalid content-type payload from mock server. Verify clean error mapping and diagnostics. HTML response when JSON expected.

Prevent duplicate side effects under retry. Critical for payments/orders/external write operations. duplicate POST with same key processed once.

Method, URL, headers, body, status handling, retries/timeouts. Assert both protocol correctness and domain mapping. 404 maps to NotFoundException.

Deterministic mock server > live internet dependency. Reliable tests enable confident refactoring and CI stability. local stub with scripted responses.

Causes hidden business errors. Always map status ranges to domain outcomes. 409 should map to conflict handling.

Threads can hang indefinitely. Missing deadlines is a major outage multiplier. blocked request threads during partner outage.

Duplicate side effects risk. Use idempotency keys or avoid automatic retries for non-idempotent operations. double charge issue.

Security/privacy risk. Redact tokens/PII and limit payload logs in production. mask account numbers.

Wrong parser assumptions. Could mis-handle HTML error pages and hide root cause. JSON parser exception on proxy HTML page.

Hard to test/maintain. Keep HTTP client wrapper separate from domain service logic. adapter layer returns typed Result objects.

Separate settings per downstream. Different dependencies need different timeout/retry/SLA policies. payment strict timeout, reporting relaxed timeout.

One place to map status/errors to exceptions. Consistency reduces duplicated bugs. 401->Unauthorized, 429->RateLimited.

Forward request context IDs. Critical for distributed tracing and incident debugging. traceparent, X-Correlation-Id.

Encode and validate inputs. Prevent malformed requests and security issues. safe query param encoding utility.

When independent calls can run concurrently. Async reduces total latency in fan-out scenarios if composed properly. fetch profile, orders, preferences in parallel.

Timeouts, selective retries, fallback, circuit breaker, metrics. Resilience is policy + observability, not just retries. per-dependency strategy object.

Backoff + jitter + capped attempts. Prevent synchronized pressure amplification during outages. exponential backoff max 3 attempts.

Respect Retry-After and throttle. Adaptive behavior protects both client and provider relationship. parse header, delay next attempt.

Return degraded response with clear semantics. Keep critical path alive while optional features fallback. recommendations missing, core order response still succeeds.

Use deterministic mock server scenarios. Script delays/failures and assert attempts + timing behavior. delayed endpoint for timeout branch.

latency, status codes, errors, retries, timeouts. Break down per dependency and per endpoint for actionable insights. dashboard for payment-provider latency p99.

tolerant reader + contract tests. Ignore non-breaking extras, fail clearly on breaking changes. DTO with ignoreUnknown + CI contract checks.

TLS controls, auth hygiene, host allowlist, redaction. Outbound calls are an attack surface and compliance concern. mTLS + strict logging policy.

Missing timeout and weak error mapping. Leads to hanging threads, unclear incidents, and brittle behavior. generic RuntimeException for all statuses.

If yes, core API usage is solid. Request construction basics are foundation for all integrations. proper headers + body + URI encoding.

If yes, concurrency understanding is strong. Correct choice impacts latency, complexity, and scalability. fan-out aggregator endpoint.

If yes, resilience maturity is good. One-size-fits-all policy is a common anti-pattern. payment vs analytics different SLAs.

If yes, correctness improves significantly. Protocol validation before payload parsing prevents subtle bugs. handle 204/HTML error body gracefully.

If yes, write-safety is strong. Idempotency thinking is critical for financial/order systems. idempotency-key strategy.

If yes, CI reliability is strong. Mock server-based tests reduce flakiness and improve confidence. scripted response scenarios.

If yes, production risk drops. TLS, allowlists, and redacted logs are non-negotiable in serious systems. reject non-HTTPS endpoints.

If yes, operations readiness is solid. Tail metrics and saturation signals guide real optimizations. p99 latency + retry spike alerts.

If yes, maintainability is high. Clean boundaries simplify testing and future protocol changes. HTTP adapter layer returns typed domain result.

Reliable networking is about policy, not just syntax. Build explicit timeouts, error handling, retries, and observability into every integration. “safe by default” outbound client template.