Master Spring 6 HTTP Interface: Build a Reactive API Client in Minutes

Spring 6 HTTP Interface Overview

Spring 6’s first GA release introduces the HTTP Interface feature, which lets developers define HTTP services as Java interfaces annotated with specific Spring annotations. Calling a method on such an interface triggers an HTTP request, similar to Feign.

Demo Setup

Create a simple Spring Boot 3 project (minimum version 3.0.0) using Java 17 or higher, and include spring-web and spring-webflux dependencies.

Define an entity class:

public class User implements Serializable {
    private int id;
    private String name;
    // constructors, getters, setters omitted
    @Override
    public String toString() {
        return id + ":" + name;
    }
}

Define a controller that returns a list of users:

@GetMapping("/users")
public List<User> list() {
    return IntStream.rangeClosed(1, 10)
        .mapToObj(i -> new User(i, "User" + i))
        .collect(Collectors.toList());
}

After starting the service, http://localhost:8080/users returns ten user objects.

Defining the HTTP Interface

Create an interface that describes the remote call:

public interface UserApiService {
    @GetExchange("/users")
    List<User> getUsers();
}

Testing the Interface

Use WebClient and HttpServiceProxyFactory to create a client instance and invoke the method:

@Test
void getUsers() {
    WebClient client = WebClient.builder().baseUrl("http://localhost:8080/").build();
    HttpServiceProxyFactory factory = HttpServiceProxyFactory.builder(WebClientAdapter.forClient(client)).build();
    UserApiService service = factory.createClient(UserApiService.class);
    List<User> users = service.getUsers();
    for (User user : users) {
        System.out.println(user);
    }
}

The console prints:

1:User1
2:User2
...
9:User9
10:User10

GetExchange (HttpExchange) Annotation

The @GetExchange annotation maps a method to an HTTP GET request. It belongs to the org.springframework.web.service.annotation package in the spring-web module. Other annotations (e.g., @PostExchange, @PutExchange) are specializations of @HttpExchange, analogous to Spring MVC’s @RequestMapping family.

Source of @HttpExchange:

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Mapping
@Reflective(HttpExchangeReflectiveProcessor.class)
public @interface HttpExchange {
    @AliasFor("url")
    String value() default "";
    @AliasFor("value")
    String url() default "";
    String method() default "";
    String contentType() default "";
    String[] accept() default {};
}

Creating the UserApiService Instance

The client is created via HttpServiceProxyFactory, which returns a proxy object. This proxy can be defined as a @Bean for injection into other components.

Other Features

Methods annotated with @HttpExchange can accept various parameter types and return any custom entity, similar to Spring MVC controllers. Custom exception handling is also supported.

Why Spring Reactive Web Dependency?

Currently, HTTP Interface is implemented only with WebClient from Spring Reactive Web. Future releases may add a RestTemplate‑based implementation.