Configuring Spring Cloud FeignClient URL

 1. Introduction

In this article, we’ll see how we can supply the target URL to a Feign Client interface.

2. Overview

To get started quickly, we’ll use mock responses for Albums, Posts, and Todos objects from the JSONPlaceholder website.

Let’s see the Album class:

public class Album {
    
    private Integer id;
    private Integer userId;
    private String title;
    
   // standard getters and setters
}

And the Post class:

public class Post {
    
    private Integer id;
    private Integer userId;
    private String title;
    private String body;
    
    // standard getters and setters
}

Finally, the Todo class:

public class Todo {
    
    private Integer id;
    private Integer userId;
    private String title;
    private Boolean completed;
    
    // standard getters and setters
}

3. Adding the Base URL in the Annotation

We can set the base URL in the url attribute in the @FeignClient annotation on the client interface. Then, we’ll annotate the methods with relevant HTTP verbs and add the required endpoint:

@FeignClient(name = "albumClient", url = "https://jsonplaceholder.typicode.com/albums/")
public interface AlbumClient {
    
    @GetMapping(value = "/{id}")
    Album getAlbumById(@PathVariable(value = "id") Integer id);
}

Let’s add a REST controller to test our client:

@RestController
public class ConfigureFeignUrlController {
    
    private final AlbumClient albumClient;
    // standard constructor
    
    @GetMapping(value = "albums/{id}")
    public Album getAlbumById(@PathVariable(value = "id") Integer id) {
        return albumClient.getAlbumById(id);
    }
    
   // other controller methods
}

This option is useful when the target URL is static throughout the application’s lifecycle.

4. Using Configuration Properties

Alternatively, for Spring Cloud version 2022.0.1 or higher, we can use the application.properties to supply the URL to the Feign Client interface. The property spring.cloud.openfeign.client.config.<interface-name>.url is used for this. Here, the <interface-name> is the value of the name attribute we provide in the @FeignClient annotation:

@FeignClient(name = "postClient")
public interface PostClient {
    
    @GetMapping(value = "/{id}")
    Post getPostById(@PathVariable(value = "id") Integer id);
}

We’ll add the base URL in the application.properties:

spring.cloud.openfeign.client.config.postClient.url=https://jsonplaceholder.typicode.com/posts/

For Spring Cloud version lower than 2022.0.1, we can set the url attribute to the @FeignClient to read the value from application.properties:

@FeignClient(name = "postClient", url = "${spring.cloud.openfeign.client.config.postClient.url}")

Next, let’s inject this client into the controller we created earlier:

@RestController
public class FeignClientController {
    private final PostClient postClient;
    
    // other attributes and standard constructor
    
    @GetMapping(value = "posts/{id}")
    public Post getPostById(@PathVariable(value = "id") Integer id) {
        return postClient.getPostById(id);
    }
    
   // other controller methods
}

This option can be useful if the target URL varies according to the application’s environment. For example, we may use mock servers for development and actual servers for the production environment.

5. Using RequestLine

Spring Cloud provides a feature in which we can override the target URL or directly supply the URL at runtime. This is achieved by using @RequestLine annotation and manually creating the feign client using the Feign Builder API to register the client:

@FeignClient(name = "todoClient")
public interface TodoClient {
    
    @RequestLine(value = "GET")
    Todo getTodoById(URI uri);
}

We need to manually create this feign client in our controller:

@RestController
@Import(FeignClientsConfiguration.class)
public class FeignClientController {
    
    private final TodoClient todoClient;
    
    // other variables
    
    public FeignClientController(Decoder decoder, Encoder encoder) {
        this.todoClient = Feign.builder().encoder(encoder).decoder(decoder).target(Target.EmptyTarget.create(TodoClient.class));
        // other initialisation
   }
    
    @GetMapping(value = "todo/{id}")
    public Todo getTodoById(@PathVariable(value = "id") Integer id) {
        return todoClient.getTodoById(URI.create("https://jsonplaceholder.typicode.com/todos/" + id));
    }
    
    // other controller methods
}

Here, we first import the default feign client configurations through FeignClientsConfiguration.class. The Feign.Builder is used for customizing these properties for the API interface. We can configure properties like encoder, decoder, connectTimeout, readTimeout, authentication, etc.

The target attribute defines on which interface these properties will apply. This interface has two implementations: EmptyTarget, which we’ve used here, and HardCodedTarget. The EmptyTarget class does not require a URL at compile time, while the HardCodedTarget does.

It is worth noting that the URI parameter provided as an argument will override the URL provided in the @feignClient annotation and the URL in the configuration properties. Similarly, the URL provided in the @FeignClient annotation will override the URL provided in the configuration properties.

6. Using a RequestInterceptor

Alternatively, another way to provide the target URL at runtime is to supply a custom RequestInterceptor to the Feign.Builder. Here, we’ll override the target attribute of the RestTemplate to update the URL to the one provided to the Feign.Builder through the requestInterceptor:

public class DynamicUrlInterceptor implements RequestInterceptor {
    private final Supplier<String> urlSupplier;
    // standard constructor

    @Override
    public void apply(RequestTemplate template) {
        String url = urlSupplier.get();
        if (url != null) {
            template.target(url);
        }
    }
}

Let’s add another method to our AlbumClient.java:

@GetMapping(value = "/{id}")
Album getAlbumByIdAndDynamicUrl(@PathVariable(name = "id") Integer id);

Instead of using the Builder in a constructor, we’ll use it in a method of ConfigureFeignUrlController to create an instance of the AlbumClient:

@RestController
@Import(FeignClientsConfiguration.class)
public class ConfigureFeignUrlController {
    
    private final ObjectFactory<HttpMessageConverters> messageConverters;
    
    private final ObjectProvider<HttpMessageConverterCustomizer> customizers;
    
    // other variables, standard constructor and other APIs
    
    @GetMapping(value = "/dynamicAlbums/{id}")
    public Album getAlbumByIdAndDynamicUrl(@PathVariable(value = "id") Integer id) {
        AlbumClient client = Feign.builder()
          .requestInterceptor(new DynamicUrlInterceptor(() -> "https://jsonplaceholder.typicode.com/albums/"))
          .contract(new SpringMvcContract())
          .encoder(new SpringEncoder(messageConverters))
          .decoder(new SpringDecoder(messageConverters, customizers))
          .target(Target.EmptyTarget.create(AlbumClient.class));
     
        return client.getAlbumByIdAndDynamicUrl(id);
    }
}

Here, we’ve added the DynamicUrlInterceptor created above that accepts a URL to override AlbumClient‘s default URL. We also configure the client to use the SpringMvcContract, SpringEncoder, and SpringDecoder.

The last two options will be useful when we need to provide support for webhooks in our application, as the target URL will vary for each client.

7. Conclusion

In this article, we saw how we can configure the target URL for Feign Client interfaces in different ways.