The Lana API supports idempotency for mutation requests. Idempotency becomes beneficial when there's a need to retry failed requests, ensuring the same operation is not performed multiple times. For instance, an operation might have already been executed, but your client didn't receive a response. Leveraging idempotency allows you to resend the same request multiple times, yet the API will only execute the operation once.

A successful mutating API request will cache and continually return the same result, given the following conditions:

1. You've supplied an Idempotency-Key HTTP header key/value in the original request, and the same key/value is used in subsequent requests.
2. The input body of a subsequent request is byte-to-byte identical to the original request.
3. The initial request was successful, and the API endpoint supports idempotency (most of our mutating API endpoints do).

The Idempotency-Key value can be any unique identifier you choose, but we recommend using UUID to avoid potential collisions.

The request response will be cached for an unspecified duration, which should be sufficient for intended use cases such as retrying requests that fail unexpectedly or due to network failures.

The Importance of Idempotency

During communication between a client and a server, a situation may arise where the server writes the result of a request to the database but fails to relay it back to the client:

Loading module

Understanding what transpired after this can be complex and may vary from case to case. However, a simple workaround can solve such situations. What if we could instruct the server: "I didn't hear back from you. Could you please repeat?". To implement this, the server needs to be able to cache our response. This is where the Idempotency-Key comes in, serving as a key that the server can use to associate the response with the request in the database cache (and thus store it temporarily). The communication employing Idempotency-Key looks like this:

Loading module