Re: [PR] Document Idempotency-Key semantics in OpenAPI [iceberg]

["c-thiel (via GitHub)" <gi...@apache.org>]

c-thiel commented on code in PR #14196:
URL: https://github.com/apache/iceberg/pull/14196#discussion_r2395139621


##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -1903,6 +1926,34 @@ components:
       schema:
         type: string
 
+    idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      schema:
+        type: string
+        format: uuid
+        minLength: 36
+        maxLength: 36
+        example: "550e8400-e29b-41d4-a716-446655440000"
+      description: |
+        Optional client-provided idempotency key for safe request retries.
+
+        When present, the server ensures no additional effects for requests that carry the same
+        Idempotency-Key within the same operation/resource scope. If a prior request with this key
+        has been finalized, the server returns the previously finalized response instead of
+        re-executing the mutation.

Review Comment:
   For some endpoints, such as `updateTable`, the response payload can be large (a full Metadata JSON). In order to implement the behavior described here, the Catalog would have to store the potentially large payload for each commit in conjunction with the otherwise lightweight idempotency key.
   
   Wouldn't the information "already processed" be enough for a client? What is the motivation to return the full previous response?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org