OAI
Support documenting API's Idempotency key
Idempotency keys (AKA Idempotent keys) is a pattern used to prevent duplicate requests by allowing the consumer of a service to send a value that represents the uniqueness of a request, so that no request with the same unique value is attempted more than once.
To know more please read:
- Patterns of Service-oriented Architecture: Idempotency Key
- Designing robust and predictable APIs with idempotency (Stripe)
Goals / Use cases
- Allow API providers like Stripe to document how they expect Idempotency keys to be provided as part of HTTP request.
- Products that support webhook APIs like Nintex workflow, Microsoft Flow and Logic Apps can understand from 3rd party API definition what represents an Idempotency key. For example in a trigger/event payloads to prevent duplicate event processing.
Notes
- Idempotency key is a request attribute, not a response attribute.
- Idempotency key is an attribute to any Open API parameter, regardless of location. As it can be in head, query and body.
- If in body, idempotency key can be in any depth of object hierarchy.
Discussion points
-
Should we enforce Idempotency keys to only be defined in POST, PATCH operations? (Since OPTIONS, HEAD, GET, PUT, DELETE are idempotent by definition)?
-
Should we allow multiple Idempotency key (attributes) to be defined in a single operation? (That could indicate that all denoted parameters/properties combined represent uniqueness)
-
Should we use
formatfor that? Seems like adding a new built-in format is easy to implement, however, this will be a blocker for API designers wanting to annotate an existing parameter with an existing format t. Also its kind of breaking the convention thatformatis describing the nature of a parameter/property itself as oppose to describing uniqueness of the request.
Thank you for the detailed issue. I wonder if this is the meaning behind the use of the x-is-unique / x-unique extensions as catalogued here.
I can see some value to both client and server tooling for such an annotation (clients would know they should provide a unique value for the parameter/property, and servers would know they should check it for uniqueness). As it (might) live within the schema object, and these objects can be reused, I would shy away from preventing use by HTTP methods. Multiple unique parameters/properties sounds very reasonable, and as you suspect, format should not be overloaded for this purpose. Knowing whether a unique / idempotencyKey parameter/property should contain a uuid or a date-time etc is valuable.
x-is-unique is added as an example for custom vendor extension in some documentation. And I wouldn't worry much about this x-unique (seems to have a different purpose).
However I think x-ms-client-request-id -also in the list- might have the same meaning, example. Documentation here and here.
I agree that being free to reuse schema definitions in more important than method checks here.
a way to support Idempotency is to follow this https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
but it is more on the how to implement not about setting a description , as it can be implemented various way
closing the ticket , as it is an implementation pattern rather than a being in OAS scope