Idempotency

​

Overview

Within the Nomba API, idempotency stands as a crucial shield against unintended outcomes resulting from duplicate requests. Although our system effectively manages idempotency, we advise that users interacting with specific endpoints such as those responsible for creating accounts or executing bank transfers, include an idempotency key X-Idempotent-key in their requests.

​

Understanding Idempotency

In the API landscape, an operation is termed idempotent if its results remain consistent, regardless of how frequently the operation is executed. Essentially, idempotency acts as a protective barrier against unintentional duplicate calls that could lead to unforeseen consequences.

For instance, consider a scenario where idempotency is not enforced for the Bank Transfer endpoint in Nomba. A successful Bank Transfer request is made, but a connection failure prevents confirmation. Uncertainty looms regarding the fate of the initial request, and if resent, it may inadvertently result in a duplicate disbursement.

To mitigate this risk, Nomba incorporates idempotency support by allowing API operations to include an idempotency key which is a unique string that guards against accidental duplicate calls.

​

Real-world Illustration

Nomba’s API provides a tangible illustration of idempotency in action, where operations can be accompanied by an idempotency key to prevent inadvertent duplicate calls and their potential adverse effects.

Lets consider the earlier Bank Transfer example

​

Scenario 1

Repeating the same Bank Transfer request with the same idempotency key prompts the endpoint to recognize it as a duplicate. Instead of processing the request again, the endpoint retrieves the response from the initial successful Bank Transfer operation.

​

Scenario 2

Using the same idempotency key but altering the Bank Transfer request (e.g., specifying a different amount) results in an error, indicating previous usage of the idempotency key.

​

Best Practices

Idempotency keys can take various forms but must be unique. Fortunately, prevalent programming languages offer functions for generating unique strings, simplifying the implementation of idempotency measures in API interactions. Adhering to such best practices ensures the robustness and reliability of Nomba’s systems, shielding against unintended consequences associated with duplicate requests. The following examples show how to get idempotent keys in popular programming languages

package main

import (
	"fmt"
	"github.com/google/uuid"
)

func main() {
	idempotentKey := uuid.New().String()
	fmt.Println(idempotentKey)
}