Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

What This Module Is (Big Picture)

The client-feign module provides a declarative REST client for Apache Fineract using OpenFeign.
Instead of manually writing HTTP request logic, developers define Java interfaces, and Feign automatically generates the HTTP calls.
This module simplifies integration by:
  • mapping Java methods to REST endpoints
  • automatically handling HTTP communication
  • serializing and deserializing JSON
It acts as a runtime implementation of the client module APIs.

Layman Example

Without Feign:
A developer must manually write HTTP requests.
Example:
plain text
QUBITS OF DPK
1POST /v1/clients
2Content-Type: application/json
And manually handle JSON responses.
With fineract-client-feign:
The developer simply calls a Java method.
Example:
plain text
QUBITS OF DPK
1clientsApi.createClient(request);
Feign automatically:
  • sends the HTTP request
  • converts the request to JSON
  • receives the response
  • converts JSON back to Java objects

Where the Code Lives

Key Package

org.apache.fineract.client.feign
Responsibilities include:
  • implementing API clients using Feign
  • configuring HTTP communication
  • managing request interceptors
  • handling authentication headers

Feign Client Interface

Feign clients map Java methods to REST endpoints.
Example client interface.
java
QUBITS OF DPK
1@FeignClient(name = "clients", url = "${fineract.server.url}")
2public interface ClientsFeignClient {
3
4    @PostMapping("/v1/clients")
5    ClientResponse createClient(@RequestBody ClientRequest request);
6
7    @GetMapping("/v1/clients/{clientId}")
8    ClientResponse retrieveClient(@PathVariable Long clientId);
9
10}
Feign automatically converts this interface into HTTP requests.

Example Feign Client Usage

An application can call the API like this:
java
QUBITS OF DPK
1ClientsFeignClient clientApi = feignBuilder.target(ClientsFeignClient.class, serverUrl);
2
3ClientRequest request = new ClientRequest();
4request.setFirstname("John");
5request.setLastname("Doe");
6
7ClientResponse response = clientApi.createClient(request);
Feign handles the HTTP request internally.

Request Interceptors

Feign clients use interceptors to add headers to requests.
Example: authentication header.
java
QUBITS OF DPK
1public class AuthenticationInterceptor implements RequestInterceptor {
2
3    @Override
4    public void apply(RequestTemplate template) {
5        template.header("Authorization", "Basic token");
6    }
7}
This ensures every request includes authentication information.

Feign Configuration

The module includes configuration for:
  • base URL
  • authentication headers
  • JSON serialization
  • request timeouts
These settings ensure reliable communication with the Fineract server.

API Communication Flow

java
QUBITS OF DPK
1External Application
2    │ Call Feign Client Method
3    ▼
4Feign Client
5    │ Convert request to HTTP
6    ▼
7HTTP Request
8    │ POST /v1/clients
9    ▼
10Fineract Server (provider module)
11    │ Process request
12    ▼
13HTTP Response
14    ▼
15Feign Client
16    │ Convert JSON response to Java object

Error Handling

Feign automatically converts HTTP errors into exceptions.
Example:
This allows applications to handle errors programmatically.

Why This Module Matters

The Feign client module allows developers to:
  • integrate with Fineract easily
  • avoid writing manual HTTP code
  • use declarative API clients
It greatly simplifies microservice and external application integrations.

One-Sentence Summary

fineract-client-feign provides a Feign-based declarative REST client implementation that allows external applications to interact with Apache Fineract APIs easily.