This is an automated email from the ASF dual-hosted git repository.
arnold pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/fineract.git
The following commit(s) were added to refs/heads/develop by this push:
new 4c341a16e FINERACT-1744 - Idempotency documentation
4c341a16e is described below
commit 4c341a16e368a9be170c3eb877bd795b7b4f1cb4
Author: Janos Haber <[email protected]>
AuthorDate: Mon Dec 19 15:47:08 2022 +0100
FINERACT-1744 - Idempotency documentation
---
.../docs/en/chapters/architecture/idempotency.adoc | 36 ++++++++++++++++++++++
.../src/docs/en/chapters/architecture/index.adoc | 2 ++
2 files changed, 38 insertions(+)
diff --git a/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc
b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc
new file mode 100644
index 000000000..c2f162884
--- /dev/null
+++ b/fineract-doc/src/docs/en/chapters/architecture/idempotency.adoc
@@ -0,0 +1,36 @@
+= Idempotency
+
+Idempotency is the way to make sure your specific action is only executed once.
+For example, if you have a button that is supposed to send a repayment, you
don’t want to repayment twice if the user clicks the button twice. Idempotency
is a way to make sure that the action is only executed once.
+
+There are two ways to use idempotency:
+
+ * HTTP Request with idempotency key header
+ * Batch request with batch item header
+
+== How it works
+
+The `idempotency key` with `action name` and `entity name` is unique, and
identify a specific command in the system.
+If no idempotency key is assigned to the request, the system will generate one
for you.
+
+1. User send a request
+2. The system checks there are already executed commands with the same
`idempotency key` and `action name` and `entity name`
+3. The action based on the result of the check
+ * If the request is completed the system return with the already generated
result
+ * If not completed, return HTTP 409 response
+ * If the request is not completed, we process the requests and store the
results in the database
+
+
+== Idempotency in HTTP requests
+
+To achieve idempotency in HTTP requests, you can use the HTTP header from
`fineract.idempotency-key-header-name` configuration variables (default
`Idemptency-Key`). This header is a unique identifier for the request. If you
send the same request twice, the second request will be ignored and the
response from the first request will be returned.
+
+== Idempotency in Batch requests
+
+In batch requests, you can set the idempotency key for every batch item, in
the batch item `header` fields. The header key is from
`fineract.idempotency-key-header-name` configuration variables (default
`Idemptency-Key`).
+
+== Result of the request
+
+* When the request is already executed and completed, the system will return a
`x-served-from-cache` header with the value `true` in the response and return
the original request body.
+* When the request is already executed but still not completed, the system
will return to HTTP 409 error code
+* When the request is not executed, the system runs it normally and stores the
result in the date
diff --git a/fineract-doc/src/docs/en/chapters/architecture/index.adoc
b/fineract-doc/src/docs/en/chapters/architecture/index.adoc
index 54f54a2dc..7bb3c4b6f 100644
--- a/fineract-doc/src/docs/en/chapters/architecture/index.adoc
+++ b/fineract-doc/src/docs/en/chapters/architecture/index.adoc
@@ -18,6 +18,8 @@ include::design.adoc[leveloffset=+1]
include::persistence.adoc[leveloffset=+1]
+include::idempotency.adoc[leveloffset=+1]
+
include::validation.adoc[leveloffset=+1]
include::batch-jobs.adoc[leveloffset=+1]
