feat: Sps-Idempotency-Key Header Proposal (#98)

nicholas-s-perkins · travisgosselin · web-flow · commit 85ec9f74540d · 2025-01-13T10:23:22.000-05:00
Supporting Reusable Model Draft: SPSCommerce/sps-api-design#161 --------- Signed-off-by: Nicholas Perkins <nicholas.s.perkins@gmail.com> Co-authored-by: Travis Gosselin <travisgosselin@users.noreply.github.com> Co-authored-by: travisgosselin <travis.gosselin@live.ca>
diff --git a/standards/request-response.md b/standards/request-response.md
@@ -442,12 +442,6 @@ Access-Control-Allow-Origin: *
 Access-Control-Allow-Methods: *
 ```
 
-<hr />
-
-```note
-**KEEP AN EYE ON IT**: The [Idempotency-Key Request header](https://tools.ietf.org/id/draft-idempotency-header-01.html) is in an experimental state but getting lots of attention as a pattern of making fault-tolerant resilient requests for traditionally non-idempotent methods like `POST`.
-```
-
 ### Custom Headers
 
 - Custom Headers **MAY** be used and created as necessary.
@@ -494,6 +488,8 @@ The usage of non-standard headers is not considered custom headers. For example,
 Sps-Cors-Error: bad origin
 ```
 
+<hr />
+
 #### Sps-Execution-Context
 
 **Type**: Both
@@ -527,6 +523,36 @@ Sps-Execution-Context:                  // values must be at least a character l
 Sps-Execution-Context: 1                // valid, but SHOULD be human-readable.
 ```
 
+<hr />
+
+#### Sps-Idempotency-Key
+
+**Type**: Request
+
+**Support**: OPTIONAL
+
+**Description**: An idempotency key is a unique value generated by the client which the resource server uses to recognize subsequent retries of the same request. The HTTP `Idempotency-Key` request header field can be used to carry an "idempotency key" to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant (related to expired RFC for [Idempotency HTTP Header Field](https://datatracker.ietf.org/doc/html/draft-idempotency-header-01)). An API must persist the Idempotency-Key in a stateful way to manage idempotency. It is common to include the idempotency key as part of the primary key or as a secondary index for the resource.
+
+- The header value **MUST NOT** be shorter than 20 characters or longer than 255.
+- The header value **MUST** not be used for `GET` requests.
+- The header value **MUST** follow this regex format: `[a-z0-9-]{20,255}`.
+- An API **MUST** return a `400` status code when the header value is in an invalid format with an appropriate error message.
+- If an action is idempotent, an API **MUST** return a `2xx` status code on conflict.
+- If an action is not idempotent, an API **MUST** return a `409` status code on conflict.
+- An API **MAY** treat this as the final primary ID of the resource or as part of the ID.
+- The header value **SHOULD** typically be a V4 UUID as a string or another random string with enough entropy to avoid collisions.
+- The header value **MUST** be generated by the client or client library.
+
+```
+// CORRECT
+Sps-Idempotency-Key: d4f885c5-2196-49c0-ba69-bc70008585ad
+Sps-Idempotency-Key: d4f885c5-2196-49c0-ba69-bc70008585ad-custom
+ 
+// INCORRECT
+Sps-Idempotency-Key: a                          // not enough entropy, and below minimum character length.
+Sps-Idempotency-Key: KG5Lxw!@#$&*()FBepaKHyUD   // non-url-safe special characters can be limiting for usage or later reference
+```
+
 ## MIME Types
 
 ### Standard MIME Types
