Subject: Re: [httpapi] Header for idempotency

From: Mark Nottingham <[email-masked]>
Date: Tue, 8 Jun 2021 14:38:15 +1000

Hi Sanjay,

Sorry for the delay in responding. I think this is interesting work, and based upon the list of folks who are already doing this (as provided below), it seems like a promising area for standardisation.

So +1 from me -- it would be good to see a Call for Adoption for this, and even better to see engagement from the folks below (or others!).

Cheers,

> On 25 May 2021, at 3:11 pm, Sanjay Dalal <[email-masked]> wrote:
> 
> Hello all,
> 
> Jayadeba and I would like to submit a draft for The Idempotency HTTP Header Field to this working group for further consideration. 
> 
> We have listed below some organizations using this header. Many of these were already using the header before we wrote the draft. Many are using the concept in their APIs but differently (listed below as well). Predominantly this header is used by fintech companies and financial orgs but we have found usage elsewhere too including in Django and https.org (HTTP for Scala).
> 
> Let us know how we can proceed. See the abstract and implementation status below.
> 
> thanks,
> sanjay
> 
> https://datatracker.ietf.org/doc/html/draft-idempotency-header-01
> 
> Abstract
> 
> The HTTP Idempotency request header field can be used to carry idempotency key in order to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant.
> 
> 
> Implementation Status
> 
> Organization: Stripe
> 
>    o  Description: Stripe uses custom HTTP header named "Idempotency-
>       Key"
>    o  Reference: https://stripe.com/docs/idempotency
> 
>    Organization: Adyen
> 
>    o  Description: Adyen uses custom HTTP header named "Idempotency-Key"
>    o  Reference: https://docs.adyen.com/development-resources/api-
>       idempotency/
> 
>    Organization: Dwolla
> 
>    o  Description: Dwolla uses custom HTTP header named "Idempotency-
>       Key"
>    o  Reference: https://docs.dwolla.com/
> 
>    Organization: Interledger
> 
>    o  Description: Interledger uses custom HTTP header named
>       "Idempotency-Key"
>    o  Reference: https://github.com/interledger/
> 
>    Organization: WorldPay
> 
>    o  Description: WorldPay uses custom HTTP header named "Idempotency-
>       Key"
>    o  Reference: https://developer.worldpay.com/docs/wpg/idempotency
> 
>    Organization: Yandex
> 
>    o  Description: Yandex uses custom HTTP header named "Idempotency-
>       Key"
>    o  Reference: https://cloud.yandex.com/docs/api-design-
>       guide/concepts/idempotency
> 
> Implementing the Concept
> 
>    This is a list of implementations that implement the general concept,
>    but do so using different mechanisms:
> 
>    Organization: Django
> 
>    o  Description: Django uses custom HTTP header named
>       "HTTP_IDEMPOTENCY_KEY"
> 
>    o  Reference: https://pypi.org/project/django-idempotency-key
> 
>    Organization: Twilio
> 
>    o  Description: Twilio uses custom HTTP header named "I-Twilio-
>       Idempotency-Token" in webhooks
> 
>    o  Reference: https://www.twilio.com/docs/usage/webhooks/webhooks-
>       connection-overrides
> 
>    Organization: PayPal
> 
>    o  Description: PayPal uses custom HTTP header named "PayPal-Request-
>       Id"
> 
>    o  Reference: https://developer.paypal.com/docs/business/develop/
>       idempotency
> 
>    Organization: RazorPay
> 
>    o  Description: RazorPay uses custom HTTP header named "X-Payout-
>       Idempotency"
> 
>    o  Reference: https://razorpay.com/docs/razorpayx/api/idempotency/
> 
>    Organization: OpenBanking
> 
>    o  Description: OpenBanking uses custom HTTP header called "x-
>       idempotency-key"
> 
>    o  Reference: https://openbankinguk.github.io/read-write-api-
>       site3/v3.1.6/profiles/read-write-data-api-profile.html#request-
>       headers
> 
>    Organization: Square
> 
>    o  Description: To make an idempotent API call, Square recommends
>       adding a property named "idempotency_key" with a unique value in
>       the request body.
> 
>    o  Reference: https://developer.squareup.com/docs/build-basics/using-
>       rest-api
> 
>    Organization: Google Standard Payments
> 
>    o  Description: Google Standard Payments API uses a property named
>       "requestId" in request body in order to provider idempotency in
>       various use cases.
> 
>    o  Reference: https://developers.google.com/standard-payments/
>       payment-processor-service-api/rest/v1/TopLevel/capture
> 
>    Organization: BBVA
> 
>    o  Description: BBVA Open Platform uses custom HTTP header called "X-
>       Unique-Transaction-ID"
> 
>    o  Reference:
>       https://bbvaopenplatform.com/apiReference/APIbasics/content/x-
>       unique-transaction-id
> 
>    Organization: WebEngage
> 
>    o  Description: WebEngage uses custom HTTP header called "x-request-
>       id" to identify webhook POST requests uniquely to achieve events
>       idempotency.
> 
>    o  Reference: https://docs.webengage.com/docs/webhooks
> -- 
> httpapi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/httpapi

--
Mark Nottingham   https://www.mnot.net/

---

From: Erik Wilde <[email-masked]>
Date: Tue, 8 Jun 2021 09:24:23 +0200

hello sanjay.

> So +1 from me -- it would be good to see a Call for Adoption for this, and even better to see engagement from the folks below (or others!).

agreeing with mark here, it's a topic that's popular enough that some 
guidance and a spec would help.

fwiw, a while ago i started something myself but never got to creating a 
first stable draft. here's a link to this abandoned effort:

https://github.com/dret/I-D/tree/master/Abandoned/idempotency-key

maybe there's something useful in there, feel free to use in any way.

cheers,

dret.

-- 
erik wilde | mailto:[email-masked] |
            | http://dret.net/netdret    |
            | http://twitter.com/dret    |

---

From: Darrel Miller <[email-masked]>
Date: Sat, 12 Jun 2021 15:54:10 +0000

Hi Sanjay,

I am supportive of a call for adoption for this draft.

Darrel

From: Erik Wilde<mailto:[email-masked]>
Sent: June 8, 2021 3:24 AM
To: Mark Nottingham<mailto:[email-masked]>; Sanjay Dalal<mailto:[email-masked]>
Cc: [email-masked]<mailto:[email-masked]>; Jayadeba Jena<mailto:[email-masked]>
Subject: Re: [httpapi] Header for idempotency

hello sanjay.

https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdret%2FI-D%2Ftree%2Fmaster%2FAbandoned%2Fidempotency-key&amp;data=04%7C01%7CDarrel.Miller%40microsoft.com%7Cd2c105f15362463502a908d92a4e79e4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637587338855377376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=c9HB64yXulJX8PAMCWIggqEx%2BeKSft1gOOiz6RN2Qw4%3D&amp;reserved=0

cheers,

dret.

--
erik wilde | mailto:[email-masked] |
            | https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdret.net%2Fnetdret&amp;data=04%7C01%7CDarrel.Miller%40microsoft.com%7Cd2c105f15362463502a908d92a4e79e4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637587338855377376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=9gO%2BlK9iaLmIp%2BP%2BfmJvwzOXdIQ1jp4D2QzrY%2BncDNo%3D&amp;reserved=0    |
            | https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Ftwitter.com%2Fdret&amp;data=04%7C01%7CDarrel.Miller%40microsoft.com%7Cd2c105f15362463502a908d92a4e79e4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637587338855377376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=7d%2FhIMx%2FfK7KKyDazl4X%2F%2BIdzbvh4GT9qoXPrm8TIPg%3D&amp;reserved=0    |

--
httpapi mailing list
[email-masked]
https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Fmailman%2Flistinfo%2Fhttpapi&amp;data=04%7C01%7CDarrel.Miller%40microsoft.com%7Cd2c105f15362463502a908d92a4e79e4%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637587338855377376%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=%2FSqaiKuppOY%2FnVpOwoFVgPlpVx2AnwP1z%2Fh0Ymi1Lvc%3D&amp;reserved=0