stevenzwu commented on code in PR #14196:
URL: https://github.com/apache/iceberg/pull/14196#discussion_r2427304871
##########
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.
+
+ Finalization rules:
+ - Finalize & replay: 200, 201, 204, and deterministic terminal 4xx
+ - Do not finalize (not stored/replayed): 5xx, 409 request_in_progress
+
+ Key Requirements:
+ - Key format: UUID (V7 preferred)
Review Comment:
> I'm not even sure there's a point of requiring a UUID (and the only set of
requiremements is probably around globally unique key and a set of allowed
characters for the key)
Agree. But we can also think that UIUD is one common way to specify the set
of requirements for globally unique key and allowed characters.
Version 7 UUID was only introduced in May 2024 in RFC 9562. Not sure if it
is universally implemented in the **standard library** of all programming
languages. Hence, the impl availability is a concern.
I just thought V4 UUID can also work equally well. Hence I thought V7 could
be recommended but it doesn't have to be required.
> I would add that having a time component as part of the key could help
mitigate the "corruption" risk if a client tries to send an operation whose key
has expired.
If client doesn't behave according the the spec requirement, there is really
no way for server to protect. E.g., client can send the same idempotency key
for a different request, or a different idempotency key for the same request.
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
