Overview

Idempotency is the property of an operation that guarantees that it can be run multiple times without changing the result of the initial request.

Idempotency is a mechanism for handling state-changing operations in distributed environments. Due to network instability, system errors, or service interruptions, client applications may make the same request multiple times by mistake. This can lead to unintended consequences such as duplicate resources or inconsistent data.

Platform APIs support idempotency in operations that create or update Intelligent Risk Platform resources by means of idempotency keys .

Idempotent operations

An idempotent operation is an API operation that can be made multiple times without producing side effects such as producing duplicate resources or inconsistent data).

The idempotency of an operation is determined by the method used.

• GET, PUT, and DELETE operations are idempotent by default.
• POST and PATCH operations are non-idempotent, but can be made idempotent by passing an idempotency key in header of the request.

Idempotency keys

An idempotency key is a string that uniquely identifies a request enabling server to recognize redundant operations and prevent duplicate transactions.

The idempotency key enables the server to recognize that despite the repeated requests, each of the subsequent requests are intended to perform the same update operation. The server processes the request, but only the initial request changes the resource.

The idempotency key must be unique. To avoid duplication Moody's Insurance Solutions recommends that the client generate a (UUID) to identify the request.

📷

Idempotency Key Expiration

The idempotency key expires after 24 hours. The client can safely retry the same operation using the key so long as the request occurs within 24 hours of the original request.

Whenever the server receives a response that passes an idempotency key, the server checks to see if it the idempotency key exists. If the idempotency key does not exist, the server processes the request and stores the idempotency key along with the outcome of the operation. If the server receives the same idempotency key again within the next 24 hours, the server returns the original result without re-processing the operation.

Example

Intelligent Risk Platform clients may pass an idempotency key in the optional x-rms-requestid header parameter of any POST or PATCH operation request.

In the following example, the request passes a idempotency key in the x-rms-requestid header parameter:

curl --request POST \
     --url https://api-euw1.rms.com/platform/perilconverter/v1/jobs \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --header 'x-rms-requestid: `a8bd2ac7-34b7-4dd1-86b7-b42d8cb02d9f`' \
     --header 'x-rms-resource-group-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \

The idempotency key in this example (i.e. a8bd2ac7-34b7-4dd1-86b7-b42d8cb02d9f) is a string that represents a 32-character UUID.