[httpapi] Header for idempotency

[Sanjay Dalal <[e-mail]>]

Hello all,

Jayadeba and I would like to submit a draft for The Idempotency HTTP Header
Field <https://datatracker.ietf.org/doc/html/draft-idempotency-header-01>
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