Idempotency

Idempotent requests to the Apache Fineract are guaranteed to be executed no more than once while running in the API Rest Idempotent mode.

Because of working with financial transactions, it is important to ensure some requests are not repeated for any reason, which may result in data loss or accidental duplication.

Application Developer must configure Application Client Requests to be idempotent by providing an Idempotency-Key header and providing in it an unique value for the request.

This will mitigate the risk of error if a API Request is retried in Apache Fineract.

For accomplish this proposal we have used the TrendyOl Jdempotent Library.

Successful API Call

When an idempotent request is processed, the status code and body of the response is associated with the idempotency key and stored in a cache. If the request is duplicated for any reason, the duplicate request will not be processed, and the response will be re-sent to the client.

Idempotency keys expire after a parameterizable time in Apache Fineract. After this time period, requests using duplicate keys will be treated as new requests.

Error API Call

Idempotent requests that fails at the Apache Fineract API Rest layer, like data validation failure, are not stored in the cache.

Subsequent API requests with the same idempotency key value during the Time To Live Period will send an message by Jdempotent to the Fineract Server, Fineract will send the following message as part of the details "Duplicated Idempotency Key was found in the cache" and a 204 NO CONTENT http code response.

Idempotency Keys

  • Idempotency keys values sent by the Client Application must be Unique. Two common strategies for generating idempotency keys are to:
  • Use an algorithm that generates a token with enough randomness and entropy.
  • Create the Idempotency key from a seed. Using the body as part of the derived key reduce the risk against double submissions.

Retry Mechanisms

The Retry Mechanisms at the Application Client side must:

  • Use the same key for initial Apache Fineract API calls and retries.
  • Retry at a reasonable frequency and rate so as not to overload the Computing Resources.
  • Properly identify and handle the error codes thrown by the Apache Fineract API layer.

Best Practices

  • Apache Fineract suggest to implement idempotency for the non safe and non idempotent methods (POST, PUT & PATCH) https verbs.
  • It is not recommend using idempotency for GET and DELETE requests, because these requests are idempotent native.
  • It is recommended to generate Idempotency Key values programmatically or by using an external key generator to ensure that all keys are secure and random Idempotency Key values.


HTTP Method

Safe

Idempotent

Requires Idempotency Key

GET

Yes

Yes

No

HEAD

Yes

Yes

No

OPTIONS

Yes

Yes

No

TRACE

Yes

Yes

No

PUT

No

Yes

Yes

DELETE

No

Yes

No

POST

No

No

Yes

PATCH

No

No

Yes

Architecture - High Level

Example - Curl Request

Example - 200 OK Response

Example - 204 No Content Response

Example - Server Response

Full log available at https://paste.apache.org/ugnuk


Full log available at https://paste.apache.org/b145d

Change Required for Supporting Idempotency Key

Full log available at https://paste.apache.org/b145d

Acknowledgments

Mehmet Arı @memojja @TrendyOl for making Open Source this great Idempotent Library and the commitment for helping us to solve queries and enhance the Jdempotent Library.

References

Apache Fineract GitHub Repository: https://github.com/apache/fineract  

Apache Fineract Release License: https://github.com/apache/fineract/blob/develop/LICENSE_RELEASE

Apache Fineract Source License: https://github.com/apache/fineract/blob/develop/LICENSE_SOURCE

Trendyol Jdempotent GitHub Repository: https://github.com/Trendyol/Jdempotent 

Trendyol Jdempotent License: https://github.com/Trendyol/Jdempotent/blob/master/LICENSE