maciejwalkowiak/spring-boot-http-clients

Spring Boot HTTP Clients provides zero-boilerplate auto-configuration for WebClient and Spring 6 HTTP Interface based HTTP clients in a Spring Boot application.

Spring Boot HTTP Clients

Spring Boot HTTP Clients provides zero-boilerplate auto-configuration for WebClient and Spring 6 HTTP Interface based HTTP clients in a Spring Boot application.

Note The project is in the early stage, so expect breaking changes.

Spring 6 introduced a new way to define HTTP clients using interfaces - HTTP Interfaces (introduction video: 🚀 New in Spring Framework 6: HTTP Interfaces).

Right now, setting up an HTTP client requires a bit of boilerplate code:

1. Create a property for the base url.
2. Create a WebClient bean which uses this property
3. Create an HttpServiceProxyFactory.

This project aims to simplify this process and provide ease of creating HTTP clients similar to Spring Cloud OpenFeign.

Note It's very likely that Spring Boot will eventually implement its own way to autoconfigure HTTP clients, and this project will become deprecated. Look for updates on this topic here: #31337

🤔 How to install

Add the dependency to spring-boot-http-clients:

<dependency>
    <groupId>com.maciejwalkowiak.spring</groupId>
    <artifactId>spring-boot-http-clients</artifactId>
    <version>0.1.1</version>
</dependency>

✨ How to use

1. Define HTTP clients in application.yml or application.properties under the prefix http.clients:

http.clients:
  todo-client:
    url: https://jsonplaceholder.typicode.com/todos
  user-client:
    url: https://jsonplaceholder.typicode.com/users

The client names (in the above example, todo-client and user-client) are just strings - use anything that makes sense - they are going to be used to construct the WebClient bean name.

The above code gets processed by WebClientsAutoConfiguration, which creates a bean of type WebClient with the name <client-name>.WebClient.

2. Define an HTTP client with Spring 6 HTTP Interface, annotate it with @HttpClient, and set the client name as the parameter:

@HttpClient("todo-client")
public interface TodoClient {
    @GetExchange
    List<Todo> get();
}

3. That's it! Now you can inject TodoClient anywhere in your code 🙃

🛠️ Advanced usage

Autoconfigured WebClient instances are the result of calling Spring Boot autoconfigured WebClient.Builder#build, which allows defining custom WebClientCustomizer that get applied on the WebClient beans.

If for any reason you cannot rely on the autoconfigured WebClient, but you still want to use autoconfigured HTTP Interface based HTTP client, make sure to create a bean with name <client-name>.WebClient, which will be picked up to create an HTTP client.

Customizing Headers

Default headers can be set in application.yml or application.properties under the prefix http.clients.<client-name>.headers key.

http.clients:
  todo-client:
    url: https://jsonplaceholder.typicode.com/todos
    headers:
      X-My-Header: my-value-x
      Y-My-Header: ${DYNAMIC_VALUE:default-value}

Customizing Cookies

Default cookies can be set in application.yml or application.properties under the prefix http.clients.<client-name>.cookies key.

http.clients:
  todo-client:
    url: https://jsonplaceholder.typicode.com/todos
    cookies:
      someCookie: cookie-value
      someDynamicCookie: ${DYNAMIC_VALUE:default-value}

Adding Filters

Filter functions can be defined in application.yml or application.properties under the prefix http.clients.<client-name>.filters key.

http.clients:
  todo-client:
    url: https://jsonplaceholder.typicode.com/todos
    filters:
      - filterFunction
      - filterFunction2

👥 Contributing

If you found a bug or a missing feature - you're very welcome to submit an issue and a pull request with a fix. Note, that this library is intended only to glue things together and not to compensate on the missing features in Spring's support for HTTP interfaces.

Sounds good? Consider ❤️ Sponsoring the project! Thank you!

spring-boot-http-clients's Issues

Add @Service for HttpClient annotation

Now if you refer HTTP Interface as bean in IntelliJ IDEA, and IDEA will report Could not autowire. No beans of 'HttpBinService' type found. .

spring-boot-http-clients relies on Spring, and @Service could be added in HttpClient annotation, and make HTTP interface as a bean.

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.TYPE})
@Documented
@Service
public @interface HttpClient {

    /**
     * Name of the {@link WebClient} bean to use with http client
     * @return bean name
     */
    String value();
}

how do we integrate with oauth2 client

Hi @maciejwalkowiak

is it possible to show an example consuming an API(mock one) that requires oauth token, for eg adding below lib

spring-boot-starter-oauth2-client

Cannot configure headers in application.yml

Hi! Does the released version contain the same source code as the one in github repository? I can see on my machine, that it doesn't contain code for configuring headers in application.yml