rrezartprebreza/spring-boot-skills / skills/spring-boot-4/http-interface-clients
http-interface-clients
VerifiedUse when calling external HTTP APIs from Spring Boot 4 / Spring Framework 7 with declarative HttpExchange interfaces. Covers ImportHttpServices, grouped base URLs and timeouts, and RestClient versus WebClient selection.
Declarative HTTP Interface Clients (Boot 4)
Define a remote API as an interface with @HttpExchange methods. Boot 4 registers the proxy with
@ImportHttpServices, so do not create a manual factory for every client.
Define and register the interface
@HttpExchange("/orders")
public interface OrderApiClient {
@GetExchange("/{id}")
OrderDto get(@PathVariable UUID id);
@PostExchange
OrderDto create(@RequestBody CreateOrderRequest request);
}
@SpringBootApplication
@ImportHttpServices(group = "orders", basePackages = "com.example.client.orders")
public class Application { }
Inject OrderApiClient like any other bean. The interface needs no @Component and no
implementation class.
Configure groups and transport
spring:
http:
clients:
connect-timeout: 2s
read-timeout: 5s
serviceclient:
orders:
base-url: https://orders.internal.example.com
read-timeout: 10s
spring.http.clients.* contains global transport defaults. spring.http.serviceclient.<group>.*
contains per-group settings, and the group name must match @ImportHttpServices.
The default client type is blocking RestClient. Select
HttpServiceGroup.ClientType.WEB_CLIENT for interfaces returning Mono or Flux, and include
the WebClient starter. Group configurers apply to a group, not one interface.
Manual HttpServiceProxyFactory wiring remains valid for one-off clients, but it is the Boot 3
pattern and should not be the default in Boot 4.
Transport failure contract
Define an adapter policy before adding retry annotations. The companion
CatalogHttpClient implements the
CatalogRetryService.CatalogTransport port from the resilience-retry skill and uses
explicit JDK connect/read timeouts. It is a small imperative adapter example, not a reason
to replace an existing HTTP interface or Boot-managed client.
| Failure | Example policy for an idempotent read |
|---|---|
| 401/403, malformed request, missing resource | Surface the domain-appropriate error; no blind retry |
| 502/503/504, connect/read timeout | Translate to the bounded retry policy |
| 429 with Retry-After | Schedule only within the caller's budget; not implemented by this example |
| Cancellation or interruption | Propagate immediately, preserving interruption |
| Invalid response body or TLS/certificate error | Diagnose; do not repeatedly retry by default |
For POST/payment calls, preserve the same idempotency key and request bytes across retries; a timeout does not prove the server did nothing. Never forward inbound Authorization to an arbitrary destination: configure credentials per trusted service. Do not allow an end user to choose the base URL. Avoid logging tokens or raw upstream error bodies.
Test the real client adapter against a stub HTTP server, including permanent status codes, transient-then-success responses, malformed bodies, delayed responses and cancellation. Keep connect, read, pool-acquisition and total deadlines distinct. When using WebClient, apply a total timeout around the whole retry sequence and avoid blocking the event loop.
See Spring REST clients.
Verification scope
The repository fixture targets Boot 4.1.0 with Java 17/21 and checks the imperative catalog adapter against a local HTTP server; not every declarative group-registration option. Check the coverage matrix before treating another minor version or an illustrative snippet as verified.
Gotchas
- Agent creates a
HttpServiceProxyFactorybean for every client - use@ImportHttpServicesand groups. - Agent adds
@Componentor an implementation to the interface - generated proxies need neither. - Agent uses
spring.http.client.*- global defaults are underspring.http.clients.*; group settings useserviceclient. - Agent hard-codes a host in
@HttpExchangeand sets a group base URL - keep the host in configuration. - Agent returns
MonoorFluxwith the default client - selectWEB_CLIENTexplicitly. - Agent assumes a group configurer customizes one interface - configure the group or separate the group.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |