Creating a Simple HTTP Service with Spring 6 HTTP Interface

Spring 6's first GA release adds the HTTP Interface feature, allowing developers to define HTTP services as Java interfaces annotated with specific Spring annotations.

To demonstrate, start by creating a Spring Boot project (version 3.0+ and Java 17+), then add a simple User entity:

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

Next, add 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 JSON list of users.

Define an HTTP Interface to call this endpoint from another component:

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

Write a test method that creates a WebClient , builds an HttpServiceProxyFactory , and invokes 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 console prints entries such as 1:User1 … 10:User10 , confirming the interface works.

The @GetExchange (formerly HttpExchange ) annotation marks a method as an HTTP GET request; similar annotations exist for other HTTP methods and are located in the org.springframework.web.service.annotation package.

Source of the HttpExchange annotation:

@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 uses Spring's proxy mechanism; currently it relies on the Reactive Web WebClient implementation, so the spring-boot-starter-webflux (or equivalent) dependency is required. Future releases may add RestTemplate support.

Beyond the basic example, methods annotated with @GetExchange can accept parameters, return custom types, and handle exceptions, mirroring the flexibility of traditional Spring MVC controllers.