This component allows you to define an HTTP client with a simple Java interface that you can then inject and use transparently in your code.

Show version
dependencies {

How to use

First, you need to create an interface annotated by @FeignApi, with each method being an HTTP call. Annotate each method with @RequestLine:

public interface Api {
    @RequestLine("GET /message")
    List<Message> getMessages();
    @RequestLine("GET /message/{id}")
    Message getMessage(@Param("id") int id);

Then, you can use this API by injecting it:

public class MyClass {
    private Api api;
    private Logger logger;
    public void someMethod() {
        List<Message> messages = api.getMessages();
        for (Message message : messages) {
            logger.info("Received message from {}", message.author);

For more information about OpenFeign, look into its documentation: https://github.com/OpenFeign/feign.


Configuration is done by

Feign is configurable by endpoint, and in its basic form is:

        com.mycompany.myapp.Api: http://base.url.to.api:port

com.mycompany.myapp.Api is the fully qualified name of your api interface, and you can add as many as you want. http://base.url.to.api:port is the base URL of this API.

With all the options, the configuration file looks like this:

            baseUrl: http://base.url.to.api:port
            encoder: feign.jackson.JacksonEncoder
            decoder: feign.jackson.JacksonDecoder
            logger: feign.slf4j.SLF4JLogger 
            logLevel: NONE
            hystrixWrapper: AUTO
            fallback: com.mycompany.myapp.Fallback

The values in this example are the default values, except for baseUrl and fallback that don’t have default values.

  • baseUrl is this only mandatory option.
  • encoder and decoder let you configure how your data is transformed when sent and received, respectively.
  • logger let you choose which logger to use to log the requests.
  • logLevel is an enum (NONE, BASIC, HEADERS, FULL).
  • hystrixWrapper is an enum (AUTO, ENABLED, DISABLED). Feign comes with Hystrix circuit-breaker support. DISABLED disables this functionality. ENABLED tells Feign to wrap all requests in Hystrix mechanism, but the lib Hystrix must be in the classpath of your project. AUTO mode will scan the classpath and if Hystrix is present, will wrap requests with it.
  • fallback takes a fully qualified class name and is only relevant when Hystrix is used. The fallback class must implement your API interface and will be used to return default values in case the requests are in error.


To call an API protected with authentication you can specify a header in your Feign interface with the @Headers annotation (example for basic authentication):

@Headers({"Authorization: Basic {credentials}"})
public interface neosdServer {

    @RequestLine("GET /file/getfilesprop")
    List<NeosdFile> getfilesprop(@Param("credentials") String credentials);

    @RequestLine("GET /file/getfiles")
    List<String> getfiles(@Param("credentials") String credentials);

Note that @Headers can also be used on individual methods.

Then, pass the credentials as method parameter. An example implementation, with credentials coming from your application configuration, coudl be:

public class MyClass {
    private String username;
    private String password;
    private NeoSdClient client;

    public void myMethod() {
        List<String> files = client.getFiles(encodeCredentials());

    private String encodeCredentials() {
        return BaseEncoding
                .encode((username + ":" + password)


A fallback class is done by implementing the Feign interface and return default values from it:

public class Fallback implements Api {
     List<Message> getMessages() {
        // return your default value here 
     Message getMessage(@Param("id") int id) {
        // return your default value here

For more information on Hystrix: https://github.com/Netflix/Hystrix/wiki

To dump the feign configuration options:

mvn -q -Dargs="feign" seedstack:config

On this page

Edit this page