Feign client error decoder

Introduction

Feign is a declarative web service client. It makes the client implementation process fast. You can simply define a Java interface with a readable method names and annotations, and make it a functioning web client. You can refer to the readme[1] to have the basic knowledge on Feign. Also there are ample of blogs that you can refer. Through this post, I am going to explain on how you can achieve Error Decoding, and Retrying functionality in a Feign client.

Setting up dependencies

This post uses spring-cloud-starter Hoxton.RELEASE version of spring cloud. In the pom file, you need to add the spring-cloud-starter-parent as the parent-pom file and spring-cloud-dependencies as the dependency management. Spring-cloud-dependencies provide the spring-cloud dependency versions according to the parent pom version. Thereafter you need to add the following dependencies for the rest of implementation:

• spring-boot-starter
• spring-boot-starter-web
• spring-cloud-starter-openfeign

It’s worth mentioning that feign was created and maintained by Netflix OSS and currently maintained separately from Nextflix. Once you wire-up all dependencies, the final pom file would look like below:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-starter-parent</artifactId>
		<version>Hoxton.RELEASE</version>
	</parent>
	<groupId>com.buddhima.testing</groupId>
	<artifactId>acn-demo</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>acn-demo</name>
	<description>Demo project for Spring Boot</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-starter-openfeign</artifactId>
		</dependency>
	</dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

Enable feign clients and define a feign client

To enable feign clients, you need to use @EnableFeignClients annotation in the main class definition. Then you can simply create an interface to the external web-services. In this post I’m not going to talk about the annotations because you can find a good documentation here [1][2]. Following is a sample interface I created for this post:

package com.buddhima.testing.demo.client;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import java.util.List;

@FeignClient(value="drmClient", url="http://www.mocky.io/v2/5e2d966a3000006200e77d2d") // to produce 400 HTTP status
public interface DrmServiceClient {

    @RequestMapping(method = RequestMethod.GET, value = "/posts")
    List<Object> getObjects();
}

Enabling logging for feign client

First I decided to talk about logging as this helps to demonstrate the behaviors in next steps.
To enable extended logging for feign clients, you need to follow two steps.

1. Enabling DEBUG log-level for feign client
2. Change feign client log-level (valid values are NONE, BASIC, HEADERS, FULL)

logging:
  level:
    com.buddhima.testing.demo.client: DEBUG

feign:
  client:
    config:
      default:
        loggerLevel: BASIC

After this configuration, you can view Request-Response logs in the microservice log. You can further increase logging by changing the logger-level to HEADER or FULL.
Throughout this post, I am discussing about configuring the feign client through application.yml file. But there are multiple ways of doing the same.

Error Decoder for Feign client

You can use error-decoder to act based on the erroneous HTTP responses. I have observed that error-decoder does not get triggered on success scenarios. To implement an error-decoder, you need to implement a class using ErrorDecoder interface and add that in the configuration.

package com.buddhima.testing.demo.client;

import feign.Response;
import feign.RetryableException;
import feign.codec.ErrorDecoder;

public class DrmClientErrorDecoder implements ErrorDecoder {
    private final ErrorDecoder defaultErrorDecoder = new Default();

    @Override
    public Exception decode(String s, Response response) {
        System.out.println("Error Response!!!");

        if (400 == response.status()) {
            System.out.println("It's a 400 Error!!!");
        }

        return defaultErrorDecoder.decode(s, response);
    }
}

logging:
  level:
    com.buddhima.testing.demo.client: DEBUG

feign:
  client:
    config:
      default:
        errorDecoder: com.buddhima.testing.demo.client.DrmClientErrorDecoder
        loggerLevel: BASIC

Retryer for Feign client

Retryer could be a useful entity to retry your request in case of failure (network failures by default). You can configure default retryer with parameters by extending Retryer.Default class.

DrmClientRetryer.java

package com.buddhima.testing.demo.client;

import feign.Retryer;

public class DrmClientRetryer extends Retryer.Default {
    public  DrmClientRetryer() {
        super();
    }
}

application.yml

feign:
  client:
    config:
      default:
        errorDecoder: com.buddhima.testing.demo.client.DrmClientErrorDecoder
        loggerLevel: BASIC
        retryer: com.buddhima.testing.demo.client.DrmClientRetryer

Furthermore, if you need to retry based on HTTP status, you can throw RetryableException at error-decoder. Same goes, if you want to retry based on HTTP-headers.

DrmClientErrorDecoder.java

package com.buddhima.testing.demo.client;

import feign.Response;
import feign.RetryableException;
import feign.codec.ErrorDecoder;

public class DrmClientErrorDecoder implements ErrorDecoder {
    private final ErrorDecoder defaultErrorDecoder = new Default();

    @Override
    public Exception decode(String s, Response response) {
        System.out.println("Error Response!!!");

        if (400 == response.status()) {
            return new RetryableException(400, response.reason(), response.request().httpMethod(), null, response.request());
        }

        return defaultErrorDecoder.decode(s, response);
    }
}

Following is a sample log, which demonstrate re-trying 5 times before giving-up.

2020-01-27 23:20:41.317 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> GET http://www.mocky.io/v2/5e2d966a3000006200e77d2d/posts HTTP/1.1
2020-01-27 23:20:42.153 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] <--- HTTP/1.1 400 Bad Request (836ms)
Error Response!!!
2020-01-27 23:20:42.317 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> RETRYING
2020-01-27 23:20:42.318 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> GET http://www.mocky.io/v2/5e2d966a3000006200e77d2d/posts HTTP/1.1
2020-01-27 23:20:42.551 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] <--- HTTP/1.1 400 Bad Request (231ms)
Error Response!!!
2020-01-27 23:20:42.776 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> RETRYING
2020-01-27 23:20:42.777 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> GET http://www.mocky.io/v2/5e2d966a3000006200e77d2d/posts HTTP/1.1
2020-01-27 23:20:43.062 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] <--- HTTP/1.1 400 Bad Request (285ms)
Error Response!!!
2020-01-27 23:20:43.400 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> RETRYING
2020-01-27 23:20:43.400 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> GET http://www.mocky.io/v2/5e2d966a3000006200e77d2d/posts HTTP/1.1
2020-01-27 23:20:43.678 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] <--- HTTP/1.1 400 Bad Request (276ms)
Error Response!!!
2020-01-27 23:20:44.185 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> RETRYING
2020-01-27 23:20:44.186 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] ---> GET http://www.mocky.io/v2/5e2d966a3000006200e77d2d/posts HTTP/1.1
2020-01-27 23:20:44.395 DEBUG 7429 --- [nio-8080-exec-1] c.b.t.demo.client.DrmServiceClient       : [DrmServiceClient#getObjects] <--- HTTP/1.1 400 Bad Request (208ms)

In the above log, you can see that same request attempted 5 times back-to-back before it was declared as a failure. You can change the default values through the Retryer implementation to desired. Furthermore, you can alter the error-decoder to refer specific HTTP headers (eg: Retry-After header).

Conclusion

Through this post, I discussed on Feign clients with two different use-cases. First you have seen, how to react based on HTTP error statuses and later about retrying requests. I hope this will be beneficial for your spring boot application development.

I have uploaded the source-code used in this post at here: https://github.com/Buddhima/feign-demo

References

[1] https://github.com/OpenFeign/feign/blob/master/README.md

[2] https://cloud.spring.io/spring-cloud-openfeign/reference/html/

[3] http://www.matez.de/index.php/2017/04/12/exploring-feign-retrying/

Over the last couple of years, I’ve been using Feign to invoke HTTP APIs, let it be external or internal. If you are not familiar with Feign, here’s a very brief intro. Feign is a declarative HTTP client. You define an interface, take some magical annotations and you have yourself a fully functioning client that you can use to communicate via HTTP.

Feign is a standalone library, anybody can use it on a project. It comes with its own annotations, types and configuration. Here’s an example client from the docs:

interface GitHub {
  @RequestLine("GET /repos/{owner}/{repo}/contributors")
  List<Contributor> contributors(@Param("owner") String owner, @Param("repo") String repo);

  @RequestLine("POST /repos/{owner}/{repo}/issues")
  void createIssue(Issue issue, @Param("owner") String owner, @Param("repo") String repo);

}

Having a tool to define APIs like this is a great way to reduce application complexity. Think about writing the same thing with Apache HttpComponents. Let me give you an idea:

CloseableHttpClient httpClient = HttpClients.createDefault();
try {
	String owner = ...
	String repo = ...
	HttpGet request = new HttpGet("https://api.github.com/repos/" 
					               + owner + "/" + repo +"/contributors");
	CloseableHttpResponse response = httpClient.execute(request);

	try {
		HttpEntity entity = response.getEntity();
		if (entity != null) {
			String result = EntityUtils.toString(entity);
			Gson gson = new Gson();
			List<Contributor> contributors = gson.fromJson(result, 
							                      new TypeToken<ArrayList<Contributor>>(){}.getType());
			...
		}
	} finally {
		response.close();
	}
} finally {
	httpClient.close();
}

I hope the difference is obvious. There’s tons of boilerplate code in the latter example.

Since Spring is one of the most used base frameworks in any Java project, there’s another level of abstraction that the Spring ecosystem provides. What if you don’t need to rely on the custom Feign annotations but you use the same Spring annotations just like when a controller is defined, e.g. @RequestMapping, @PathVariable and so on.

Well, Spring Cloud adds this capability to your application. The former example with Spring annotations looks the following:

@FeignClient("github")
interface GitHub {
  @RequestMapping(value = "/repos/{owner}/{repo}/contributors", method = GET)
  List<Contributor> contributors(@PathVariable("owner") String owner, @PathVariable("repo") String repo);

  @RequestMapping(value = "/repos/{owner}/{repo}/issues", method = POST)
  void createIssue(Issue issue, @PathVariable("owner") String owner, @PathVariable("repo") String repo);

}

Quite neat compared to the previous examples.

Although, there’s one downside to any abstraction. Or maybe downside is not even the best word to describe it, its rather a trade-off that we – engineers – often forget.

One of the points of an abstraction is to hide details from its users to ease development, which is absolutely spot on in case of Feign. However, the trade-off you are going to make is less control over that particular piece of code. For normal use-cases it’s often perfectly fine but as soon as you hit a wall and you need some specific behavior, you have to start digging. Where? I guess most of us just Google for some time, hoping that somebody has asked a similar question on Stackoverflow. Sometimes it’s just not the case, and you have to jump right into the code to figure out how to work-around the framework.

Error handling in Feign

Fortunately the framework creators have thought about having some way of reacting to errors during an API call. The ErrorDecoder interface is used for that purpose.

public interface ErrorDecoder {
  public Exception decode(String methodKey, Response response);
}

Such an interface implementation can be tied to creating a particular Feign client. In the standard Feign world, you can specify it during the Builder calls, like:

Feign.builder()
.decoder(new CustomDecoder())

So you can customize the Decoder you’d like to use on a per client basis, but not on a method basis. That’s just a limitation of the capabilities the library is providing.

How does this look in the Spring world? If you’d like to use an ErrorDecoder, you can just simply register it as a bean and the framework will automatically pick it up and assign it to every Feign client.

@Configuration
public class CustomFeignConfiguration {
    @Bean
    public CustomDecoder customDecoder() {
        return new CustomDecoder();
    }
}

Very neat, but since within an application there could be several Feign clients used, does it make sense to use a single decoder for all clients? Probably not. But even if you go one level deeper, you might need to have different error handling logic for different API calls within the same client.

The junior implementation

So if you were carefully reading, you might have noticed a parameter in the signature of the ErrorDecoder, methodKey. The methodKey is automatically generated by the Feign library whenever an error response is received from the downstream API. An example methodKey looks the following:

UserServiceClient#findById(UUID)

It starts with the Feign client class name, then a hash symbol and then the name of the method, followed by its parameter types within parentheses. The key generation can be found here: Feign#configKey

The first implementation one might think would be some kind of string magic on the methodKey:

@Override
    public Exception decode(String methodKey, Response response) {
        if (methodKey.startsWith("UserServiceClient")) {
           // dosomething specific to UserServiceClient
        } else if (...) {
           ...
        }
    }

Obviously this is going to work, but it won’t scale and as soon as you rename a class/method, you’ll end up in some functional problems in your application since the String renaming might be easily messed up (even though IDEs are very smart these days).

Testing is going to be hell with an implementation like this, cyclomatic complexity is going to increase with the number of clients and API methods. There must be a solution out there and somebody must have figured it out already.

Well, I thought the same, but so far I haven’t found anything on this.

The proper solution

First of all, this solution is aiming to address Spring only, when using the bare Feign client library, there are some minor tweaks required.

For a Spring Cloud based Feign client, you need to use the @FeignClient annotation on the interface like this:

@FeignClient(name = "user-service", url = "http://localhost:9002")
public interface UserServiceClient {
    @GetMapping("/users/{id}")
    UserResponse findById(@PathVariable("id") UUID id)
}

Pretty easy I’d say. So what happens when there’s an error, for example 404 returned by the API?

2020-09-29 20:31:29.510 ERROR 26412 --- [ctor-http-nio-2] a.w.r.e.AbstractErrorWebExceptionHandler : [c04278db-1]  500 Server Error for HTTP GET "/users/d6535843-effe-4eb7-b9ff-1689420921a3"

feign.FeignException$NotFound: [404] during [GET] to [http://localhost:9002/users/d6535843-effe-4eb7-b9ff-1689420921a3] [UserServiceClient#findById(UUID)]: []

As you can see, the original API I was calling resulted in a 500 Internal Server Error because the downstream user-service was responding with a 404. Not good.

So what can I do if I want to translate this 404 response into a UserNotFoundException within the service? And what if I’d like to do something else for another method within the same client?

Well, let’s create a generic ErrorDecoder that can defer the error handling to other classes, similarly how we do with a @ControllerAdvice and @ExceptionHandler class in the Sprint MVC world.

I’m going to use a custom annotation to mark methods or the client class which needs special treatment on its error handling:

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface HandleFeignError {
    Class<? extends FeignHttpExceptionHandler> value();
}

FeignHttpExceptionHandler is a simple interface with a single method:

public interface FeignHttpExceptionHandler {
    Exception handle(Response response);
}

The usage is going to look the following:

@FeignClient(name = "user-service", url = "http://localhost:9002")
public interface UserServiceClient {
    @GetMapping("/users/{id}")
    @HandleFeignError(UserServiceClientExceptionHandler.class)
    UserResponse findById(@PathVariable("id") UUID id) throws UserNotFoundException;
}

The implementation for UserServiceClientExceptionHandler is very simple:

@Component
public class UserServiceClientExceptionHandler implements FeignHttpExceptionHandler {
    @Override
    public Exception handle(Response response) {
        HttpStatus httpStatus = HttpStatus.resolve(response.status());
        String body = FeignUtils.readBody(response.body());
        if (HttpStatus.NOT_FOUND.equals(httpStatus)) {
            return new UserNotFoundException(body);
        }
        return new RuntimeException(body);
    }
}

Of course you can make it more sophisticated, this is just an example.

So how does the annotation work? As I said, we are going to use a special ErrorDecoder. First of all, we have to understand the signature of the ErrorDecoder interface. Since there’s no information within the decoder which client’s which method was called, somehow we have to figure it out so we can invoke the corresponding error handler.

One way to do it is to utilize the methodKey parameter and build a map based on that with the error handlers. But before that, we need to somehow get a reference to all the Feign clients registered within the application:

@Component
@RequiredArgsConstructor
public class ExceptionHandlingFeignErrorDecoder implements ErrorDecoder {
    private final ApplicationContext applicationContext;

    private final Map<String, FeignHttpExceptionHandler> exceptionHandlerMap = new HashMap<>();

    @EventListener
    public void onApplicationEvent(ContextRefreshedEvent event) {
        Map<String, Object> feignClients = applicationContext.getBeansWithAnnotation(FeignClient.class);
        List<Method> clientMethods = feignClients.values().stream()
                .map(Object::getClass)
                .map(aClass -> aClass.getInterfaces()[0])
                .map(ReflectionUtils::getDeclaredMethods)
                .flatMap(Arrays::stream)
                .collect(Collectors.toList());
        for (Method m : clientMethods) {
            String configKey = Feign.configKey(m.getDeclaringClass(), m);
            HandleFeignError handlerAnnotation = getHandleFeignErrorAnnotation(m);
            if (handlerAnnotation != null) {
                FeignHttpExceptionHandler handler = applicationContext.getBean(handlerAnnotation.value());
                exceptionHandlerMap.put(configKey, handler);
            }
        }
    }

    private HandleFeignError getHandleFeignErrorAnnotation(Method m) {
        HandleFeignError result = m.getAnnotation(HandleFeignError.class);
        if (result == null) {
            result = m.getDeclaringClass().getAnnotation(HandleFeignError.class);
        }
        return result;
    }
}

First off, it’s loading all the Spring beans with the @FeignClient annotation. Since Feign is based on interfaces, there are JDK proxies involved, that’s why we need to call aClass.getInterfaces()[0] to get the actual interface with its methods.

Then the only trick is to calculate the methodKey which I’m doing using the Feign.configKey method call (that’s the one Feign is also using). And as well we’re searching for the HandleFeignError annotation on method and on class level in the same order.

So as soon as the Spring context is set up, we’ll have a map of methodKeys to actual exception handlers.

The second thing we need to do is to make sure this class implements the ErrorDecoder interface.

@Component
@RequiredArgsConstructor
public class ExceptionHandlingFeignErrorDecoder implements ErrorDecoder {
    private final ErrorDecoder.Default defaultDecoder = new Default();
    
    // rest is omitted for simplicity

    @Override
    public Exception decode(String methodKey, Response response) {
        FeignHttpExceptionHandler handler = exceptionHandlerMap.get(methodKey);
        if (handler != null) {
            return handler.handle(response);
        }
        return defaultDecoder.decode(methodKey, response);
    }
}

So the decode method is very simple. If the map contains the methodKey with its corresponding exception handler, we’ll use that for resolving the proper Exception, otherwise the solution is falling back to the Default ErrorDecoder.

Using the Feign client afterwards is quite easy:

            try {
                UserResponse userResponse = userServiceClient.findById(id);
                // do something with the UserResponse
            } catch (UserNotFoundException e) {
                // Oops, the user is not found in the system
                // let's do some error handling
            }

Conclusion

With this solution in place, you can easily define proper error handling on the level of Feign client methods with any custom logic/custom exceptions you want to use. It allows you to build a more maintainable and robust application.

As usual, if you are interested in more, follow me on Twitter for updates.

UPDATE: the code can be found on my GitHub here.

Feign is a declarative web service client.
It makes writing web service clients easier.
To use Feign create an interface and annotate it.
It has pluggable annotation support including Feign annotations and JAX-RS annotations.
Feign also supports pluggable encoders and decoders.
Spring Cloud adds support for Spring MVC annotations and for using the same HttpMessageConverters used by default in Spring Web.
Spring Cloud integrates Eureka, Spring Cloud CircuitBreaker, as well as Spring Cloud LoadBalancer to provide a load-balanced http client when using Feign.

@SpringBootApplication
@EnableFeignClients
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

@FeignClient("stores")
public interface StoreClient {
    @RequestMapping(method = RequestMethod.GET, value = "/stores")
    List<Store> getStores();

    @RequestMapping(method = RequestMethod.GET, value = "/stores")
    Page<Store> getStores(Pageable pageable);

    @RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")
    Store update(@PathVariable("storeId") Long storeId, Store store);

    @RequestMapping(method = RequestMethod.DELETE, value = "/stores/{storeId:\d+}")
    void delete(@PathVariable Long storeId);
}

@FeignClient(name = "stores", configuration = FooConfiguration.class)
public interface StoreClient {
    //..
}

@FeignClient(name = "${feign.name}", url = "${feign.url}")
public interface StoreClient {
    //..
}

@Configuration
public class FooConfiguration {
    @Bean
    public Contract feignContract() {
        return new feign.Contract.Default();
    }

    @Bean
    public BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
        return new BasicAuthRequestInterceptor("user", "password");
    }
}

spring:
    cloud:
        openfeign:
            client:
                config:
                    feignName:
                        url: http://remote-service.com
                        connectTimeout: 5000
                        readTimeout: 5000
                        loggerLevel: full
                        errorDecoder: com.example.SimpleErrorDecoder
                        retryer: com.example.SimpleRetryer
                        defaultQueryParameters:
                            query: queryValue
                        defaultRequestHeaders:
                            header: headerValue
                        requestInterceptors:
                            - com.example.FooRequestInterceptor
                            - com.example.BarRequestInterceptor
                        responseInterceptor: com.example.BazResponseInterceptor
                        dismiss404: false
                        encoder: com.example.SimpleEncoder
                        decoder: com.example.SimpleDecoder
                        contract: com.example.SimpleContract
                        capabilities:
                            - com.example.FooCapability
                            - com.example.BarCapability
                        queryMapEncoder: com.example.SimpleQueryMapEncoder
                        micrometer.enabled: false

spring:
    cloud:
        openfeign:
            client:
                config:
                    default:
                        connectTimeout: 5000
                        readTimeout: 5000
                        loggerLevel: basic

@FeignClient(contextId = "fooClient", name = "stores", configuration = FooConfiguration.class)
public interface FooClient {
    //..
}

@FeignClient(contextId = "barClient", name = "stores", configuration = BarConfiguration.class)
public interface BarClient {
    //..
}

@Configuration
public class CustomConfiguration{

@Bean
public FeignClientConfigurer feignClientConfigurer() {
            return new FeignClientConfigurer() {

                @Override
                public boolean inheritParentConfiguration() {
                    return false;
                }
            };

        }
}

@Import(FeignClientsConfiguration.class)
class FooController {

    private FooClient fooClient;

    private FooClient adminClient;

    @Autowired
    public FooController(Client client, Encoder encoder, Decoder decoder, Contract contract, MicrometerObservationCapability micrometerObservationCapability) {
        this.fooClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerObservationCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("user", "user"))
                .target(FooClient.class, "https://PROD-SVC");

        this.adminClient = Feign.builder().client(client)
                .encoder(encoder)
                .decoder(decoder)
                .contract(contract)
                .addCapability(micrometerObservationCapability)
                .requestInterceptor(new BasicAuthRequestInterceptor("admin", "admin"))
                .target(FooClient.class, "https://PROD-SVC");
    }
}

@Configuration
public class FooConfiguration {
    @Bean
    @Scope("prototype")
    public Feign.Builder feignBuilder() {
        return Feign.builder();
    }
}

@Configuration
public class FooConfiguration {
    @Bean
    public CircuitBreakerNameResolver circuitBreakerNameResolver() {
        return (String feignClientName, Target<?> target, Method method) -> feignClientName + "_" + method.getName();
    }
}

@FeignClient(url = "http://localhost:8080")
public interface DemoClient {

    @GetMapping("demo")
    String getDemo();
}

feign:
  circuitbreaker:
    enabled: true
    alphanumeric-ids:
      enabled: true
resilience4j:
  circuitbreaker:
    instances:
      DemoClientgetDemo:
        minimumNumberOfCalls: 69
  timelimiter:
    instances:
      DemoClientgetDemo:
        timeoutDuration: 10s

@FeignClient(name = "test", url = "http://localhost:${server.port}/", fallback = Fallback.class)
    protected interface TestClient {

        @RequestMapping(method = RequestMethod.GET, value = "/hello")
        Hello getHello();

        @RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
        String getException();

    }

    @Component
    static class Fallback implements TestClient {

        @Override
        public Hello getHello() {
            throw new NoFallbackAvailableException("Boom!", new RuntimeException());
        }

        @Override
        public String getException() {
            return "Fixed response";
        }

    }

@FeignClient(name = "testClientWithFactory", url = "http://localhost:${server.port}/",
            fallbackFactory = TestFallbackFactory.class)
    protected interface TestClientWithFactory {

        @RequestMapping(method = RequestMethod.GET, value = "/hello")
        Hello getHello();

        @RequestMapping(method = RequestMethod.GET, value = "/hellonotfound")
        String getException();

    }

    @Component
    static class TestFallbackFactory implements FallbackFactory<FallbackWithFactory> {

        @Override
        public FallbackWithFactory create(Throwable cause) {
            return new FallbackWithFactory();
        }

    }

    static class FallbackWithFactory implements TestClientWithFactory {

        @Override
        public Hello getHello() {
            throw new NoFallbackAvailableException("Boom!", new RuntimeException());
        }

        @Override
        public String getException() {
            return "Fixed response";
        }

    }

@FeignClient(name = "hello", primary = false)
public interface HelloClient {
    // methods here
}

public interface UserService {

    @RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
    User getUser(@PathVariable("id") long id);
}

@RestController
public class UserResource implements UserService {

}

package project.user;

@FeignClient("users")
public interface UserClient extends UserService {

}

spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.response.enabled=true

spring.cloud.openfeign.compression.request.enabled=true
spring.cloud.openfeign.compression.request.mime-types=text/xml,application/xml,application/json
spring.cloud.openfeign.compression.request.min-request-size=2048

logging.level.project.user.UserClient: DEBUG

@Configuration
public class FooConfiguration {
    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}

@Configuration
public class FooConfiguration {
    @Bean
    Capability customCapability() {
        return new CustomCapability();
    }
}

@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerObservationCapability micrometerObservationCapability(ObservationRegistry registry) {
        return new MicrometerObservationCapability(registry);
    }
}

@Configuration
public class FooConfiguration {
    @Bean
    public MicrometerCapability micrometerCapability(MeterRegistry meterRegistry) {
        return new MicrometerCapability(meterRegistry);
    }
}

public interface DemoClient {

    @GetMapping("/demo/{filterParam}")
    @Cacheable(cacheNames = "demo-cache", key = "#keyParam")
    String demoEndpoint(String keyParam, @PathVariable String filterParam);
}

// Params.java
public class Params {
    private String param1;
    private String param2;

    // [Getters and setters omitted for brevity]
}

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/demo")
    String demoEndpoint(@SpringQueryMap Params params);
}

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/stores")
    CollectionModel<Store> getStores();
}

@GetMapping("/objects/links/{matrixVars}")
Map<String, List<String>> getObjects(@MatrixVariable Map<String, List<String>> matrixVars);

@FeignClient("demo")
public interface DemoTemplate {

    @GetMapping(path = "/stores")
    CollectionModel<Store> getStores();
}

@FeignClient(name = "demo")
protected interface PageableFeignClient {

    @CollectionFormat(feign.CollectionFormat.CSV)
    @GetMapping(path = "/page")
    ResponseEntity performRequest(Pageable page);

}

@Autowired
ObjectProvider<TestFeignClient> testFeignClient;

spring.cloud.openfeign.autoconfiguration.jackson.enabled=false

spring.cloud.openfeign.client.refresh-enabled=true

spring.cloud.openfeign.oauth2.enabled=true

@Bean
public LoadBalancerFeignRequestTransformer transformer() {
    return new LoadBalancerFeignRequestTransformer() {

        @Override
        public Request transformRequest(Request request, ServiceInstance instance) {
            Map<String, Collection<String>> headers = new HashMap<>(request.headers());
            headers.put("X-ServiceId", Collections.singletonList(instance.getServiceId()));
            headers.put("X-InstanceId", Collections.singletonList(instance.getInstanceId()));
            return Request.create(request.httpMethod(), request.url(), headers, request.body(), request.charset(),
                    request.requestTemplate());
        }
    };
}

spring.cloud.loadbalancer.x-forwarded.enabled=true

Spring Cloud OpenFeign an openfeign integration module for spring boot. Feign is one of the best HTTP clients which we could use with Spring boot to communicate with third-party REST APIs. In this tutorial, we are going to explain how we can configure feign client inside a spring boot app to consume third party REST API.

Additionally, we are going to configure the same feign client in order to support real-world scenarios in development.

Major Topics inside this article, You can just click on the area you looking for if you need exact answer.

1. Advantage of Using Feign as an HTTP Client
2. Adding Required Dependencies
3. Configuring Feign Client
4. Send Requests Using Feign Client
5. Testing With Postman
6. Loading Feign Configurations From Application Properties
7. Custom Configurations For Feign Client in Spring Boot
8. Setting Dynamic Headers into the Feign Client
9. Setting Feign Configurations Using Application Properties
10. Configure Error Handling For Feign Client in Spring Boot

Advantage of Using Feign as an HTTP Client

As I discovered the main advantage in using feign for an HTTP client is that all we need to do is write an interface with pre-defined annotations and feign automatically do the stuff that needs to happen inside a REST client.

Let’s start coding,

Let’s create a fresh spring boot application using spring initializr, If you are not familiar with creating a spring boot application just use our guide on HOW TO CREATE A SPRING BOOT PROJECT. Here I’m using Lombok plugin to keep the code simple and clean. If you need to learn how we can use lombok in spring boot follow our article Guide to use Lombok In Spring Boot.

Adding Required Dependencies

In order to integrate Feign Client we need to include ‘spring-cloud-starter-openfeign’ along with ‘spring-cloud-dependencies’ into our project. In this tutorial, I’m using Gradle as a project building tool.

To do that add following dependencies into build.gradle,

implementation 'org.springframework.cloud:spring-cloud-dependencies:Hoxton.RELEASE'
implementation 'org.springframework.cloud:spring-cloud-starter-openfeign:2.2.5.RELEASE'

Configuring Feign Client

All right, now we are ready to configure feign client inside this project. So let’s start coding to consume third party API.

Here we are using the third party fake API with pagination to consume using feign client. This API is hosted and open to consume for free. There are many API endpoints that cover all the HTTP methods.

First, we need to enable feign client inside the application by using ‘@EnableFeignClients’ annotation in the main class.

package com.javatodev.feign;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.openfeign.EnableFeignClients;

@SpringBootApplication
@EnableFeignClients
public class OpenFeignIntegrationApplication {

    public static void main(String[] args) {
        SpringApplication.run(OpenFeignIntegrationApplication.class, args);
    }

}

then we can start creating the interface which will act as the client for this API. To do that we just need to create an interface inside the project.

package com.javatodev.feign.client;

import com.javatodev.feign.rest.response.Airline;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import java.util.List;

@FeignClient(value = "instantwebtools-api", url = "https://api.instantwebtools.net/v1/")
public interface ApiClient {

    @RequestMapping(method = RequestMethod.GET, value = "/airlines")
    List<Airline> readAirLines();

    @RequestMapping(method = RequestMethod.GET, value = "/airlines/{airlineId}")
    Airline readAirLineById(@PathVariable("airlineId") String airlineId);

}

In this example, we are going to consume the following API endpoints and it returns Airline Response.

https://api.instantwebtools.net/v1/airlines
https://api.instantwebtools.net/v1/airlines/:id

Response class for the API.

package com.javatodev.feign.rest.response;

import lombok.Data;

@Data
public class Airline {
    private Long id;
    private String name;
    private String country;
    private String logo;
    private String slogan;
    private String headQuaters;
    private String website;
    private String established;
}

Here we should set value which is the identifier for this API client and URL which is the base URL to the 3rd party API we are going to consume.

Send Requests Using Feign Client

All right now we are ready to consume this API through our application.

For the moment I’ll call the API with a simple Rest Controller. But in real world application these APIs could be called from a service or repository or anywhere you preferred inside a Spring Boot project.

package com.javatodev.feign.controller;

import com.javatodev.feign.client.ApiClient;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import lombok.RequiredArgsConstructor;

@RestController
@RequestMapping(value = "/airlines")
@RequiredArgsConstructor
public class AirlineController {

    private final ApiClient apiClient;

    @GetMapping
    public ResponseEntity readAirlineData (@RequestParam(required = false) String airlineId) {
        if (airlineId == null) {
            return ResponseEntity.ok(apiClient.readAirLines());
        }
        return ResponseEntity.ok(apiClient.readAirLineById(airlineId));
    }

}

Testing With Postman

Loading Feign Configurations From Application Properties

There was few hard coded values which we have used in ApiClient. We can load those configurations from application.properties since those are constants in many cases and it will be easy to change whenever needed. To do that just need to add key value pair into the propeties and we could use those inside ApiClient as below.

app.feign.config.name=instantwebtools-api
app.feign.config.url=https://api.instantwebtools.net/v1/

Then we need to add these keys into the ApiClient in order to capture values from properties.

package com.javatodev.feign.client;

import com.javatodev.feign.rest.response.Airline;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import java.util.List;

@FeignClient(value = "${app.feign.config.name}", url = "${app.feign.config.url}")
public interface ApiClient {

    @RequestMapping(method = RequestMethod.GET, value = "/airlines")
    List<Airline> readAirLines();

    @RequestMapping(method = RequestMethod.GET, value = "/airlines/{airlineId}")
    Airline readAirLineById(@PathVariable("airlineId") String airlineId);

}

Custom Configurations For Feign Client in Spring Boot

Feign support custom clients instead of default client. Eg;- OkHttp client which allows using HTTP/2. Additionally, there are multiple clients that support feign client in Spring boot to add more value additions to the feign.

Here we are going to create an additional class with @configuration to achieve overriding to default client with OKHTTP client.

package com.javatodev.feign.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import feign.Logger;
import feign.okhttp.OkHttpClient;

@Configuration
public class CustomFeignClientConfiguration {
    
    @Bean
    public OkHttpClient client() {
        return new OkHttpClient();
    }

    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.FULL;
    }
}

Then we should add these configurations into the feign client we developed by using configuration in @FeignClient

@FeignClient(value = "${app.feign.config.name}", url = "${app.feign.config.url}", configuration = CustomFeignClientConfiguration.class)

Here I’m explaining ways to set HTTP headers to feign client. This is since in some cases we need to set dynamic headers like authentication tokens, basic auth credentials, auth identification, content type and etc, to a request we are sending to a 3rd party API.

Setting headers on top of the request

This is the most common and easiest way to set header into the feign client.

@RequestMapping(method = RequestMethod.GET, value = "/airlines")
    List<Airline> readAirLines(@RequestHeader("X-Auth-Token") String token);

But if we use this pattern we should add same into the every API endpoint where it should be applicable and we need to pass every header while sending a request.

Setting global headers to the feign client

Let’s assume our 3rd party API requires the following headers to be present with every request which is coming to the resources.

• Content-Type:application/json
• Accept:application/json
• X-Auth-Code: 920d4d0b85443d98d86cb3c8c81d9eed

We can achieve this using feign.RequestInterceptor. Basically, this adds header values to every and each request going through the feign client in Spring boot. There are two ways of configuring RequestInterceptor with a spring boot application.

In here we can use the same configuration class which we written for above step to add requestinterceptor to set dynamic headers into every and each request foing through feign client in spring boot.

We just need to add below code snippet into our configuration class.

@Bean
    public RequestInterceptor requestInterceptor() {
        return requestTemplate -> {
            requestTemplate.header("Accept", "application/json");
            requestTemplate.header("Content-Type", "application/json");
            requestTemplate.header("X-Auth-Code", "920d4d0b85443d98d86cb3c8c81d9eed");
        };
    }

Here in this example I’ve only used hard coded value for X-Auth-Code, But if you need to add dynamic authentication credentials or a tokens, just add it here.

Setting Feign Configurations Using Application Properties

We can define feign client properties using application.properties or yaml as well. This is since there is no need of having some configurations inside java based configurations instead of application properties. Eg:- connection time out value.

Let’s see how we can set those values using application.properties

feign.client.config.default.connect-timeout=20000
feign.client.config.default.read-timeout=20000

Here we have set global configuration for every and each feign client defined inside this spring boot project. But what if you need to set different configurations to different clients? It’s possible with feign client too.

To do that you just need to do is adding the feign client name instead of default to the configuration.

feign.client.config.instantwebtools-api.connect-timeout=20000
feign.client.config.instantwebtools-api.read-timeout=20000

Configure Error Handling For Feign Client in Spring Boot

In this case feign give us feign.codec.ErrorDecoder to capture and handle errors inside feign client. Basically you just need to write error CustomErrorDecoder which decodes any type of error happens inside feign communication.

package com.javatodev.feign.config;

import feign.Response;
import feign.codec.ErrorDecoder;
import lombok.extern.slf4j.Slf4j;

@Slf4j
public class FeignCustomErrorDecoder implements ErrorDecoder {

    @Override public Exception decode(String methodKey, Response response) {

        switch (response.status()) {
            case 400:
                log.error("Error in request went through feign client");
                //handle exception
                return new Exception("Bad Request Through Feign");
            case 401:
                log.error("Error in request went through feign client");
                //handle exception
                return new Exception("Unauthorized Request Through Feign");
            case 404:
                log.error("Error in request went through feign client");
                //handle exception
                return new Exception("Unidentified Request Through Feign");
            default:
                log.error("Error in request went through feign client");
                //handle exception
                return new Exception("Common Feign Exception");
        }
    }

}

Here I haven’t handled the exception, But in your case, you could create custom exceptions and handle these errors with whatever the exception you like on cases which added here.

Then, we need to introduce this error decoder into the feign configuration which we created earlier by adding following,

@Bean
public ErrorDecoder errorDecoder() { return new FeignCustomErrorDecoder();}

Reading original error message from feign error decoder

Here as what we have defined feign doesn’t give you the original error message which coming from the third party API. But we can read the original error using feign decoder as below.

package com.javatodev.feign.config;

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.javatodev.feign.rest.response.FeignExceptionMessage;

import org.apache.commons.io.IOUtils;

import java.io.IOException;
import java.io.Reader;
import java.nio.charset.StandardCharsets;

import feign.Response;
import feign.codec.ErrorDecoder;
import lombok.extern.slf4j.Slf4j;

@Slf4j
public class FeignCustomErrorDecoder implements ErrorDecoder {

    @Override public Exception decode(String methodKey, Response response) {

        //START DECODING ORIGINAL ERROR MESSAGE
        String erroMessage = null;
        Reader reader = null;

        //capturing error message from response body.
        try {
            reader = response.body().asReader(StandardCharsets.UTF_8);
            String result = IOUtils.toString(reader);
            ObjectMapper mapper = new ObjectMapper();
            mapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
            FeignExceptionMessage exceptionMessage = mapper.readValue(result,
                FeignExceptionMessage.class);

            erroMessage = exceptionMessage.getMessage();

        } catch (IOException e) {
            log.error("IO Exception on reading exception message feign client" + e);
        } finally {
            try {
                if (reader != null) {
                    reader.close();
                }
            } catch (IOException e) {
                log.error("IO Exception on reading exception message feign client" + e);
            }
        }

        //END DECODING ORIGINAL ERROR MESSAGE
        
        switch (response.status()) {
            case 400:
                log.error("Error in request went through feign client {} ", erroMessage);
                //handle exception
                return new Exception("Bad Request Through Feign");
            case 401:
                log.error("Error in request went through feign client {} ", erroMessage);
                //handle exception
                return new Exception("Unauthorized Request Through Feign");
            case 404:
                log.error("Error in request went through feign client {} ", erroMessage);
                //handle exception
                return new Exception("Unidentified Request Through Feign");
            default:
                log.error("Error in request went through feign client {} ", erroMessage);
                //handle exception
                return new Exception("Common Feign Exception");
        }
    }

}

Conclusion

In this article we’ve discussed How to Use Feign Client in Spring Boot along with few more additional configurations, value additions to the feign client setup with spring boot like error handling, defining configurations, etc.

You can find source codes for this tutorial from our Github.