Master Spring 6 HTTP Interface: Build a GetExchange Demo from Scratch

Demo Overview

Spring Framework 6 introduces the HTTP Interface feature, allowing developers to declare HTTP services as Java interfaces annotated with specific markers. The article builds a minimal demo to illustrate this capability.

Step 1 – Create a Simple HTTP Service

Start a new Spring Boot (≥3.0.0) project with Java 17, and add spring-web and spring-webflux (Spring Reactive Web) dependencies.

Define a serializable User entity:

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

Create a controller that returns a list of ten users:

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

Run the application and verify that http://localhost:8080/users returns the expected JSON array.

Step 2 – Define the HTTP Interface

Declare an interface that represents the remote service. The only required annotation is @GetExchange (a specialization of @HttpExchange).

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

Step 3 – Create a Client Proxy

Use Spring’s HttpServiceProxyFactory together with a WebClient to obtain an implementation of the interface:

@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 output shows the ten user records (e.g., 1:User1 … 10:User10).

Understanding @GetExchange and Related Annotations

The @GetExchange annotation marks a method as an HTTP GET request. It resides in the org.springframework.web.service.annotation package of the spring-web module. Other HTTP‑specific annotations (e.g., @PostExchange, @PutExchange) are specializations of the base @HttpExchange annotation, similar to Spring MVC’s @GetMapping and @PostMapping.

Key elements of @HttpExchange include: value / url: request path method: HTTP method (default derived from the specific annotation) contentType, accept: media‑type handling

In the demo only the URL is specified; other attributes take default values.

Why Spring Reactive Web Is Required

The current implementation of HTTP Interface relies on WebClient, which belongs to Spring Reactive Web. Therefore, the project must include the spring-boot-starter-webflux (or the equivalent reactive dependency). Future Spring releases may add a RestTemplate -based implementation.

Additional Features

Beyond the basic example, methods annotated with @HttpExchange can accept various parameter types (path variables, request bodies, headers) and return any custom type. Custom exception handling is also supported.

Conclusion

The article demonstrates how to use Spring 6’s HTTP Interface to replace manual RestTemplate or Feign calls with a type‑safe, annotation‑driven client. It covers project setup, interface definition, proxy creation, and the role of Reactive Web. Readers are encouraged to explore further features and upcoming enhancements.