Simplify AI-Powered HTTP Services with Spring’s New Service Registry

Based on official Spring documentation and supplemented with AI‑related examples, this article introduces the enhancements to Spring’s HTTP service client.

Since Spring Framework 6 introduced the @HttpExchange annotation, defining HTTP services via Java interfaces has become exceptionally simple, which is especially valuable in the AI era for calling various third‑party AI compute services.

As shown, the PIG AI platform fully leverages the powerful capabilities of the HTTP Interface to achieve perfect compatibility with non‑standard (non‑OpenAI) protocol interfaces, satisfying the advanced service concepts required by frameworks such as Spring AI and LangChain4j while reusing existing model monitoring and retry mechanisms for clearer, more maintainable code.

public interface AiAssistantArkService {

    /**
     * Generate image
     * @param request Image generation request parameters
     * @return Image generation response
     */
    @PostExchange("/images/generations")
    AiImageArkCompletionsDTO.Response generateImage(@RequestBody AiImageArkCompletionsDTO.Request request);
}

In a configuration class the AI service can be declared as follows:

public AiAssistantArkService buildArkAssistant(AiModelEntity model) {
    JdkClientHttpRequestFactory jdkClientHttpRequestFactory = new JdkClientHttpRequestFactory();
    jdkClientHttpRequestFactory.setReadTimeout(Duration.ofSeconds(aiKnowledgeProperties.getConnectTimeout()));

    RestClient.Builder builder = restClientBuilderOptional.orElseGet(RestClient::builder)
        .requestFactory(jdkClientHttpRequestFactory)
        .baseUrl(model.getBaseUrl())
        .defaultHeader(HttpHeaders.AUTHORIZATION, String.format("Bearer %s", model.getApiKey()));

    if (aiKnowledgeProperties.isShowLog()) {
        builder.requestInterceptor(new RestClientLoggingInterceptor());
    }

    HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(RestClientAdapter.create(builder.build()))
        .build();
    return factory.createClient(AiAssistantArkService.class);
}

LLM‑driven applications usually involve multiple cooperating components (prompt templates, chat memory, LLM, output parsers, RAG components such as embedding models and stores) and many interactions, making coordination cumbersome. Developers can focus on business logic rather than low‑level details; Java AI can now elegantly wrap these AI services as standard Spring beans with unified configuration and scheduling.

Configuration Overhead Pain Points

While the HTTP service client is powerful and expressive, the configuration becomes repetitive as the number of client proxies grows, especially when each non‑standard model (e.g., Volcano, Baillian audio models) requires a separate service factory, further increasing complexity.

@Bean
MilestoneService milestoneService(HttpServiceProxyFactory factory) {
    return factory.createClient(MilestoneService.class);
}

@Bean
ReleaseService releaseService(HttpServiceProxyFactory factory) {
    return factory.createClient(ReleaseService.class);
}

// More client beans …

@Bean
HttpServiceProxyFactory proxyFactory(RestClient.Builder clientBuilder) {
    RestClient client = clientBuilder.baseUrl("https://api.github.com").build();
    return HttpServiceProxyFactory.builderFor(RestClientAdapter.create(client)).build();
}

HTTP Service Registry: Ultimate Solution

To solve this challenge, Spring Framework 7 introduces an additional registry layer on top of HttpServiceProxyFactory, providing the following capabilities:

Configure Model : Register HTTP interfaces and initialize the underlying HTTP client infrastructure.

Transparent Creation : Automatically create and register client proxies as Spring beans.

Unified Access : Access all client proxies via HttpServiceProxyRegistry.

In the configuration model, HTTP services are organized into groups, where a group is a set of services sharing the same HTTP client configuration and generated client instances.

Declarative Registration

The new @ImportHttpServices annotation (added in Spring Framework 7) can declare HTTP service groups.

Manual Listing of HTTP Services

@ImportHttpServices(group = "github", types = {MilestoneService.class, ...})
@ImportHttpServices(group = "stackoverflow", types = {QuestionService.class, ...})
@Configuration
public class DemoConfig {
}

Package Scanning Detection

@ImportHttpServices(group = "github", basePackages = "client.github")
@ImportHttpServices(group = "stackoverflow", basePackages = "client.stackoverflow")
@Configuration
public class DemoConfig {
}

HTTP service groups default to using RestClient, but the clientType attribute can switch them to WebClient.

Programmatic Registration

Step 1: Create Registrar

public class CustomHttpServiceRegistrar extends AbstractHttpServiceRegistrar {
    @Override
    protected void registerHttpServices(GroupRegistry registry, AnnotationMetadata metadata) {
        registry.forGroup("github").detectInBasePackages("client.github");
        // More registrations …
    }
}

Step 2: Import Registrar

@Configuration
@Import(CustomHttpServiceRegistrar.class)
public class ClientConfig {
}

HTTP Client Initialization

After declaring HTTP service groups, configure the HTTP client for each group using an HttpServiceGroupConfigurer bean:

@Bean
RestClientHttpServiceGroupConfigurer groupConfigurer() {
    return groups -> {
        groups.filterByName("github").forEachClient((_, builder) ->
            builder.baseUrl("https://api.github.com"));
        groups.filterByName("stackoverflow").forEachClient((_, builder) ->
            builder.baseUrl("https://api.stackexchange.com?site=stackoverflow"));
    };
}

Ecosystem Integration

Spring Boot 4.0 Integration

Spring Boot 4.0 transparently auto‑configures RestClient and WebClient for each group, providing per‑group HTTP client property support:

# Global configuration
spring.http.client.service.read-timeout=2s

# GitHub group configuration
spring.http.client.service.group.github.base-url=https://api.github.com

# StackOverflow group configuration
spring.http.client.service.group.stackoverflow.base-url=https://api.stackexchange.com

Other Integrations

Spring Cloud 2025.1 : Provides transparent load‑balancing and circuit‑breaker support for HTTP service groups.

Spring Security 7.0 : Offers OAuth support for HTTP service groups via @ClientRegistrationId on methods annotated with @HttpExchange.

Summary

The new HTTP service registry lets applications declare HTTP services and configure the underlying client infrastructure while the framework handles the rest, offering an extensible mechanism for powerful, out‑of‑the‑box HTTP client initialization.

Main Advantages

Simplified Configuration : Eliminates repetitive bean declarations.

Unified Management : Organizes HTTP services by group.

Ecosystem Integration : Seamlessly works with Spring Boot, Spring Cloud, and Spring Security.

Flexible Configuration : Supports both declarative and programmatic registration approaches.