How to configure OpenFeign with Spring boot

In this tutorial, we will discuss how to configure OpenFeign and a Feign client in a Spring boot application in order to make a REST call to a REST API service in another application.

The goal of this tutorial is to get you started with OpenFeign basics in Spring boot and to demonstrate how you can leverage the power of external REST APIs in your own Spring boot application. If OpenFeign is already configured in your Spring boot application, then I would recommend that you check out our more advanced tutorial about configuring and customizing feign clients to perform different HTTP operations (PUT, POST, GET, DELETE).

If you are reading this article, then you are probably working on or thinking about building an ecosystem of microservices based on Spring Boot, Docker and Spring cloud. If you would like to improve your skills in that area and read about lessons learned from another experienced software architect, then I would recommend that you check out Hands-On Microservices with Spring Boot and Spring Cloud (click to check price and reviews on Amazon).

Short introduction to OpenFeign and Netflix Feign

Feign is a Java to HTTP client binder. Feign allows you to create HTTP request templates (AKA Feign clients) which correspond to REST or SOAP requests to an external API. These clients can then be reused to send requests to the target API based on parameters and arguments that your application needs.

The way Feign works is that it processes annotations to create a reusable HTTP template. Those annotations are configured by the developer to indicate which service and endpoint they are calling.

In some articles, you will find that they call the Feign project “Netflix Feign”. This is the old project name and it has been renamed to “OpenFeign” a few years ago. So please do not be confused by those two names as they both indicate the same project. However, it is also interesting to note that Feign is no longer used by Netflix anymore.

We will not dig too deep into the history of OpenFeign, but if you would like to learn more, then please check out the project’s Github page.

Configuring Feign for Spring Boot

In our example, we will be using Spring Boot 2.4.2 and Java 11. But you should be able to reuse our tutorial for newer versions of Java and Spring Boot.

Adding required dependencies for OpenFeign

Let us get started by adding the required dependencies to our POM. The first and most important step is add the correct version of the spring-cloud-dependencies POM to your dependency management section in your POM which corresponds to your Spring boot version.

This allows you add other dependencies from Spring Cloud into your project without worrying about compatibility between the different modules. You can find the compatibility matrix below

Spring Boot version	spring-cloud-dependencies version
2.4.x	2020.0.x AKA Ilford
2.3.x	Hoxton (SR5+)
2.2.x	Hoxton
2.1.x	Greenwich
2.0.x	Finchley
1.5.x	Dalston and Edgware

Each of these spring-cloud-dependencies “releases” come in different versions as well, designated with SR1, SR2…. etc. You can find those SR versions in the central maven repository here. Please also check the latest compatibility matrix info on the official Spring cloud homepage.

Since we are using Spring boot 2.4.2, we will also use the spring cloud dependencies version 2020.0.1.

	<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>org.springframework.cloud</groupId>
				<artifactId>spring-cloud-dependencies</artifactId>
				<version>2020.0.1</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

To get started with feign clients, you will also need to add the spring-cloud-starter-config and the spring-cloud-starter-openfeign dependencies to your POM’s dependencies section.

		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-starter-config</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-starter-openfeign</artifactId>
		</dependency>

Enabling Feign clients in Spring boot

Now that our required dependencies are ready, it is time to configure Spring boot to detect Feign clients and make them available. This is easily done by adding the @EnableFeignClients annotation to your application.

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

@EnableFeignClients
@SpringBootApplication
public class DemoApplication {

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

}

By adding the @EnableFeignClients annotation, you instruct Spring to scan your packages for interfaces which contain the @FeignClient annotation to make those clients available for use inside your Spring application.

How to create a Feign Client

Now that our application is ready for use with OpenFeign, it is time to write our first Feign client. For this example, we will create a very simple client which fetches data from a different, locally hosted Spring boot application.

Let us assume that our target host is “localhost:1234”. Our API has two services. One is at “/api/server/firstService” and the second in “/api/server/secondService”.

To create a Feign client in Spring, we will need to use the @FeignClient annotation.

package com.nullbeans.demo.clients;

import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;

@FeignClient(name = "localServiceClient", url = "localhost:1234", path = "/api/server")
public interface LocalServiceClient {

    @GetMapping("/firstService")
    String getServerFirstServiceData();

    @GetMapping("/secondService")
    String getServerSecondServiceData();

}

We use the @GetMapping annotation from the Spring Web framework to indicate that we intend to use the HTTP GET verb when interacting with the service. Notice how we built our feign client with the following properties:

• name: this is the name of the service. This can be used to differentiate between different clients (the same as we would do with Spring beans).
• url: the location of the target host. In this case, this is our localhost with port number 1234.
• path: this is the path prefix to the target API. This prefix will be prepended to all methods in the client.

Each of the individual methods indicate in our interface indicates an action on our target API. The method annotation indicates the HTTP verb to be used when calling the API and the sub-path to the API.

For example, to perform an HTTP GET, we use the @GetMapping annotation. For HTTP POST, we use @PostMapping and so on. In the end, the target API location will consist of:

client url + client path + method annotation path

How to use a Feign client

The nice thing about using Feign and Spring together is that creating and using Feign clients work almost in the same way as regular Spring beans. For example, if you would like to use the LocalServiceClient that we created earlier, then you can just inject the interface into your Spring service or controller.

package com.nullbeans.demo;

import com.example.demo.clients.LocalServiceClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/client")
public class DemoController {

    final LocalServiceClient localServiceClient;

    public DemoController(LocalServiceClient localServiceClient){
        this.localServiceClient = localServiceClient;
    }

    @GetMapping("/firstService")
    public String delegateFirstService(){
        return localServiceClient.getServerFirstServiceData();
    }


}

In our DemoController, we inject the LocalServiceClient interface and simply call the the method that corresponds to the API endpoint that we need.

Summary

OpenFeign is a very useful framework that can be used to interact with external systems and make use of external APIs. The framework can be easily integrated with Spring boot which enables you to rapidly develop and test your systems with external APIs.