REST API Integration with Feign HTTP client

1. Introduction

In projects we often have some integrations with API layer of 3rd party systems. This means that on our side we need to prepare HTTP client to be able consume those endpoints. Based on API specification we need to prepare Resource representation classes. Then, HTTP client with some configurations, like headers, timeouts, error handling. Parse request and response payloads into objects and many other things. All off this on the end creates a lot of boilerplate code.

Inspired with my latest project I want to introduce Feign HTTP client. Feign is HTTP client which goal is to simplify writing HTTP clients. Goal is to reduce complexity of REST API integrations.

With Feign we need to declare and annotate an interface based on API specification. And in background Feign will process annotations into a templated requests. Feign offers you to configure different HTTP clients, JSON/XML processors, metric providers, loggers and some other features.

2. Example

Throughout this article, we will integrate Faker APIs in Adobe Experience Manager (AEM) project. Goal is to get some fake generated data about users and addresses.

3. Setup

First, in your AEM project add needed dependencies.

<!-- Feign -->
<dependency>
  <groupId>io.github.openfeign</groupId>
  <artifactId>feign-core</artifactId>
  <version>11.0</version>
</dependency>
<dependency>
  <groupId>io.github.openfeign</groupId>
  <artifactId>feign-jackson</artifactId>
  <version>11.0</version>
</dependency>
<!--Jackson -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
  <version>2.12.0</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-annotations</artifactId>
  <version>2.12.0</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.12.0</version>
</dependency>

Besides the feign-core , additionaly we'll use feign-jackson for JSON processing. _ Feign-jackson _ requires jackson-core , jackson-annotations and _ jackson-databind _ dependencies.

To prevent unresolved import packages, we need to install those dependencies in Apache Felix Web console or embed them into our project bundle.

Embed dependencies in _ filevault-package-maven-plugin _ configuration.

<embedded>
  <groupId>io.github.openfeign</groupId>
  <artifactId>feign-core</artifactId>
  <target>/apps/aem-feign-vendor-packages/application/install</target>
</embedded>
<embedded>
  <groupId>io.github.openfeign</groupId>
  <artifactId>feign-jackson</artifactId>
  <target>/apps/aem-feign-vendor-packages/application/install</target>
</embedded>
<embedded>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
  <target>/apps/aem-feign-vendor-packages/application/install</target>
</embedded>
<embedded>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-annotations</artifactId>
  <target>/apps/aem-feign-vendor-packages/application/install</target>
</embedded>
<embedded>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <target>/apps/aem-feign-vendor-packages/application/install</target>
</embedded>

4. Feign HTTP client

First of all we need to prepare Resource representation classes.

@Data
public class Users {

    private String uuid;
    private String firstname;
    private String lastname;
    private String username;
    private String password;
    private String email;
    private String ip;
    private String macAddress;
    private String website;
    private String image;

}

@Data
public class Address {

    private String street;
    private String streetName;
    private String buildingNumber;
    private String city;
    private String zipcode;
    private String country;

    @JsonProperty("county_code")
    private String countyCode;

    private Double latitude;
    private Double longitude;

}

@Data
public class Response<T> {

    private String status;
    private int code;
    private long total;
    private List<T> data;

}

Next step is to define FakerApi client which follows Faker endpoints specification. The @RequestLine annotation defines HTTP method and UriTemplate for request. Expressions wrapped in curly-braces are resolved using their corresponding @param annotated parameters.

public interface FakerApi {

    @RequestLine("GET /users?_quantity={quantity}&_gender={gender}")
    Response<Users> users(@Param("quantity") long quantity, @Param("gender") String gender);

    @RequestLine("GET /addresses?_quantity={quantity}")
    Response<Address> addresses(@Param("quantity") long quantity);

}

Last thing is to create FakerApi client and that's all.

FakerApi fakerApi = Feign.builder()
                     .decoder(new JacksonDecoder())
                     .target(FakerApi.class, "https://fakerapi.it/api/v1");

Response<Address> address = fakerApi.addresses(2);
Response<Users> femaleUsers = fakerApi.users(2, "female");