Spring HTTP Clients
Use for outbound integration code: a new peer client, an ineffective timeout, missing
TLS/observation configuration, an HTTP interface proxy, leaked responses, or unsafe
failure mapping. Preserve a sound existing client and the requested outcome: design,
diagnosis, review or implementation. A RestTemplate call is not authorization to
migrate the application.
Establish the actual client
Inspect the compiler/toolchain and resolved Boot, Framework and transport versions, the caller's execution model, client factories, effective configuration and peer API contract. This skill's authoring and worked-example baseline is Java 25, Boot 4.1.1, Framework 7.0.9, using managed dependencies and no preview features. Report differences in the target project; do not silently upgrade it or add a starter to make a copied snippet work. Boot minor releases can change configuration names.
Trace one invocation from its caller through proxy, client, factory/connector, interceptors/filters and any retry layers. Collect the evidence that changes the fix: which factory runs, which phase stalled, actual attempts, response size, pending pool acquisitions or the last authoritative mutation result. A timeout alone proves no particular transport or remote outcome. If evidence is missing, retain that uncertainty and identify the smallest discriminating check; continue independent local work.
For a new integration, inspect the consuming use case, provider specification/version, existing adapters, tests, ADRs and deployment/egress configuration. Establish whether the remote result is mandatory, optional or asynchronous; who owns credentials and tenant context; and which latency, concurrency, cost or quota constraints affect calls. Check the existing client, gateway/service mesh and platform conventions before adding retry, rate or connection policies. A declared gateway is not evidence of its policy.
Separate established contracts, reversible implementation assumptions and unresolved business choices. Ask only what the available evidence cannot answer and would change the solution: for a charged mutation with an uncertain outcome, ask what replay/lookup guarantee the provider offers; recommend retaining the original intent while that is unknown. If outage behavior is unspecified, ask whether the use case must stop, remain pending or can omit the result; do not invent a successful fallback. Group decisive questions and continue independent mapping/configuration work. A narrow timeout repair does not reopen settled product policy or require a new integration design.
Make the boundary explicit
| Situation | Decision and verification |
|---|---|
| Imperative caller, ordinary finite response | Prefer the project's configured RestClient. Virtual threads can run blocking calls but do not supply downstream admission control. |
| Reactive caller or existing reactive stream | Preserve a composed WebClient pipeline. Keep blocking calls and .block() off event loops; identify cancellation and body ownership. |
| Typed remote API contract | On a compatible Boot release, use an @HttpExchange interface registered by @ImportHttpServices and peer group properties. Preserve an adequate existing client; an interface is not required for one call. |
| Configured settings appear ineffective | Follow the injected Boot builder and selected transport to the wire. A separately created client may bypass customizers; a later connector/factory replacement can discard earlier settings. |
| Caller reports failure after a mutation | Preserve the intent and unresolved outcome until the provider contract resolves it. A timeout, cancellation or 5xx is not evidence of no effect. |
When defining the consumed response contract, constructing clients, selecting a factory/connector, configuring TLS, or preserving context, read wiring and transports.
For a material choice, record the constraint, viable options and why the chosen owner fits: apply a missing required bound, reuse a proven platform policy, clarify an unknown provider guarantee, defer a broader migration with its trigger, or omit a mechanism without a demonstrated need. Record only consequential decisions. A low-volume lookup can need a finite timeout without needing a breaker; a provider concurrency cap can require admission control even when every call has a timeout. Do not infer quota or retry permission from the chosen client API.
For an ordinary finite response, start with a DTO and the framework's body extraction and status handling. Add a peer adapter when it translates a real protocol or domain contract, not merely to wrap every client method. Manual proxy factories, raw stream decoders and new exception hierarchies need a constraint that simpler Boot facilities cannot satisfy. HTTP interfaces still inherit the underlying transport and failure contract; they do not make mutations retry-safe or responses size-limited.
Match the project's architecture at the integration boundary. If application code uses
domain ports, implement that port in a peer-specific HTTP adapter and keep provider DTOs,
HTTP statuses and Spring client types there. Name the operation and peer explicitly;
avoid an unrelated generic HttpService shared by every business capability. A small
consumer with no such boundary can use its configured typed client directly. Returning
ResponseEntity<T> from inbound controllers does not require exposing it in domain ports.
When constructing clients programmatically, use injected Boot builders at the application composition boundary. Builders are mutable; clone before diverging configurations when reusing one instance. Keep per-user credentials out of singleton default headers and define the destination to which they may be sent. Account for transport cookie stores too: separate authorization headers do not isolate a shared session cookie. Do not create a transport or pool per call.
Bound work and retain its outcome
Before changing a timeout or adding resilience, read failure, time and response bounds. Keep these decisions visible at the call site:
- Name the phase each limit covers: admission/pool lease, connect/TLS, response, body and complete logical operation. A read setting is not a portable end-to-end deadline. Do not mutate a shared client for each request's remaining budget.
- Establish the response-size contract for success and error data. For untrusted
or large bodies, enforce the required bound before aggregation; use existing codec
or transport facilities before writing a decoder. Decide how streams end and release
resources.
Content-Lengthalone is not a bound, and a byte cap is not a time limit. - Separate status/transport evidence from retry permission.
429can carry delay advice;400/401normally require correction, not repeated identical calls. Apply the peer's documented semantics. Never retry allRestClientExceptioninstances. - Give the logical operation one retry owner, account for transport/proxy attempts, and release failed responses before backoff. An idempotency header works only when the provider supports its identity, retention and replay contract.
- Keep endpoint templates and bounded result categories in metrics. Raw URLs, tokens, request/response bodies and exception messages may disclose secrets or create unbounded labels. Observation wiring does not prove propagation through a custom executor or reactive boundary.
Implement, verify and deliver
For implementation, first fix the consumed success/failure contract and ownership; then wire the smallest compatible change through the existing composition boundary; finally exercise the changed contract and update its consumer/operation documentation. Include required configuration and dependencies in the same deliverable. For a broad integration, track unresolved provider decisions and progress in the project's existing format; use an ADR for a durable transport/policy ownership choice, not each DTO mapping. For diagnosis or review, produce the evidenced finding and a discriminating next check instead of treating an untested candidate configuration as a confirmed fix.
When adding a client or substantiating a failure/lifecycle claim, read verification. Use the project's Spring test facilities for its actual client path; the worked example is a pattern, not a separate application to import. A mock request test can prove serialization or headers; only a real transport test can exercise the chosen timeouts, cancellation and connection behavior.
Deliver the focused change or finding, actual versions and selected transport, the operation/error contract, checks run and unverified boundaries. Scale this to the task; no new resilience framework, benchmark or lengthy report is required for a simple client. For a maintained integration, use the documentation guidance in wiring and transports. Stop when the requested contract has evidence and remaining limits are clear. Consult version-matched official documentation or source when an API/property is uncertain; name unavailable verification and the evidence needed to resolve it, rather than inventing configuration or treating this skill's baseline as the project's version.
Optional handoffs
spring-boot: pass builder registration, conditions and property origins for missing auto-configuration; expect a composition/configuration correction.timeouts-and-deadlines: pass phase settings, caller budget and release observations for a shrinking deadline and cancellation design.retries-and-backoffandidempotency: pass all attempt owners, operation identity, provider replay/reconciliation contract and unresolved outcomes; expect a safe retry policy or explicit stop/recovery state.circuit-breakersandconcurrency-limiting-and-bulkheads: pass scoped failures, saturation and downstream capacity for admission/degradation decisions. A breaker does not by itself limit simultaneous calls.distributed-tracing-designandspring-boot-observability: pass the client creation path, propagation boundary and observed telemetry for trace design or Boot wiring.java-application-security-basics: pass credential ownership, authorization rules and secret-bearing types for code-level access and disclosure review. Transport trust, allowed destinations and redirects stay in this skill's wiring analysis.
These are optional collaborators. If unavailable, retain the guards here and state
the missing evidence. Server endpoint contracts belong to spring-boot-web; do not
activate this skill merely because an inbound controller uses HTTP.