Spring HTTP service groups: configure one host policy for several interfaces

Group by transport policy

A pricing API may expose QuoteClient and DiscountClient on the same host. Register both in one HTTP service group when they share base URL, authentication and connection policy. A payments client with a tighter timeout or distinct credentials belongs in another group even if its host happens to match. Spring Framework can declare groups with @ImportHttpServices and apply configuration through an HTTP service group configurer. The annotated interface still describes only the request shape.

Watch duplicate types

If the same interface is registered under two groups, injection by interface type becomes ambiguous. Resolve it by group through the proxy registry or use distinct interfaces. A broad package scan can unintentionally include a new interface during a rollout; explicit registration is easier to review for a small client surface. Token scope must match the group that owns the remote call.

Test the intended host

Bring up two local stub servers and give each group a different base URL. Assert QuoteClient reaches the pricing server and the payments interface reaches the payment server, including failure status handling. A unit test that calls a mocked interface cannot detect a group wired to the wrong host. The snippet declares the group; the transport configurer is application-specific.

Implementation sketch

@Configuration
@ImportHttpServices(group = "pricing",
    types = {QuoteClient.class, DiscountClient.class})
class RemotePricingClients {
    // Configure the pricing group base URL, auth and timeouts together.
}

Cost and verification

Grouping removes repeated client setup but can broaden the impact of a bad shared timeout or credential. Keep metrics by remote operation even when clients share one pool.

Common Mistakes

• Do not group clients solely because their Java interfaces sit in one package.
• Do not inject a duplicated interface by type without resolving its group.
• Do not assume group registration supplies a correct base URL or timeout automatically.

Read next

Spring HTTP service client: the interface is a contract, not a transport policy, Spring HTTP client timeouts: bound the call inside the request deadline, Spring HTTP service client retries: an interface cannot prove the server did not commit, Spring OAuth2 client tokens: bind the authorized client to the intended caller and host.