Idempotency

Idempotency in a REST API ensures that making the same request multiple times has the same effect on the server and results in the same response. This principle is critical for ensuring reliability, especially in distributed systems where network issues can occur and retries are necessary.

Idempotency is implemented by including an idempotency key in the request's Idempotency-Key HTTP header. Idempotency keys are stored for 24 hours, so generated idempotency keys should be unique within that time frame. The client is responsible for ensuring the idempotency key's uniqueness.

Endpoints that support idempotency can be recognized by the fact that they accept the Idempotency-Key header. Idempotent processing comes with the following notes:

The request body and the complete URL of retried requests must match precisely with the original request. This includes the order of the attributes in any JSON payload. If there is a mismatch, the server will return a 409 error with the type /silverflow/problems/idempotency/request-body-mismatch.
If you retry the request while the initial request is still pending, the endpoint will return a 503 retriable error with the type /silverflow/problems/idempotency/request-is-still-being-processed. You can retry again after observing a wait time or wait for a response to the initial request.
Silverflow needs to maintain an internal state to provide idempotent processing of charges. If this state becomes unavailable, the system will return a 503 retriable error with the type: /silverflow/problems/idempotency/temporarily-unavailable. If this is the case, it is possible to retry the request without the Idempotency-Key header. This will instruct the server to process the request without idempotency.

For all other endpoints that don't support idempotency keys, it is advised to use the conditional update mechanism. This mechanism is currently most useful for provisioning, such as updating merchants and merchant acceptors.

Conditional Updates

In some cases, multiple processes interact with the API simultaneously, which could lead to an object being updated twice simultaneously. This could result in the lost update problem, in which changes from the first update are 'overwritten' by the second update.

To avoid this problem, any update (HTTP PATCH) operation should be accompanied by an If-Match header containing the object's version. The update will succeed when the object being updated still has that version. However, if a different process changes the object, the update operation will fail with a 412 Precondition Failed. When this is the case, it is up to the client to resolve this situation.

The contents of the If-Match header can be derived in two ways:

The value can be taken from the ETag response header when the object is retrieved through a GET operation.
The value can be taken from the version attribute of the object.