How to Use Spring 6 HTTP Interface for Simple REST Calls

Introduction

Most developers still use httpclient, okhttp, etc. The author suggests using Feign and notes that Spring 6 introduces the HTTP Interface feature, allowing developers to define HTTP services as Java interfaces with annotated methods.

Demo

First create a simple HTTP service with a Spring Boot project.

Entity class:

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

Controller:

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

Run the service and verify http://localhost:8080/users returns ten users.

Then create a new Spring Boot project (Spring Boot 3.0+, Java 17) and add Spring Web and Spring Reactive Web dependencies.

Define an HTTP Interface:

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

Test 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);
    }
}

Output shows user IDs and names.

GetExchange (HttpExchange) Annotation

GetExchange triggers an HTTP GET request. Spring also provides other HttpExchange‑derived annotations, similar to @RequestMapping/@GetMapping in MVC.

These annotations reside in org.springframework.web.service.annotation. Example 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 UserApiService Instances

The service instance is created via HttpServiceProxyFactory, which returns a proxy object. It can also be defined as a @Bean for injection.

Other Features

Methods annotated with HttpExchange can accept various parameters, return custom entity types, and support custom exception handling.

Why Spring Reactive Web Dependency

Reactive Web provides WebClient, the current implementation for HTTP Interface. Future versions may add RestTemplate support.

Conclusion

The article gives a quick overview of Spring 6 HTTP Interface and encourages further exploration.