Subject: [httpapi] Header for idempotency

From: Sanjay Dalal <[email-masked]>
Date: Mon, 24 May 2021 22:11:16 -0700

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

---

From: Martin J. Dürst <[email-masked]>
Date: Tue, 25 May 2021 16:26:05 +0900

Hello Sanjay, others,

I had a quick look. I'm not familiar with the details.

However, I think the title of this draft should not be
"The Idempotency HTTP Header Field", but "The Idempotency-Key HTTP 
Header Field". Same for some of the section titles in the draft.

Also, putting BCP 14 keywords in quotes in the actual text looks really 
strange. Maybe the text

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
    "OPTIONAL" in this document are to be interpreted as described in BCP
    14 [RFC2119] [RFC8174] when, and only when, they appear in all
    capitals, as shown here.

should be changed to

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
    "OPTIONAL" in this document are to be interpreted as described in BCP
    14 [RFC2119] [RFC8174] when, and only when, they appear in all
    capitals, as shown here, and without quotes.

Some text such as

    The idempotency key that is supplied as part of every "POST" request
    MUST be unique and "MUST" not be reused with another request with a
    different request payload.

is otherwise difficult to interprete. What's the difference between MUST 
and "MUST"? It looks like "MUST" isn't meant seriously.

Regards,    Martin.

-- 
Prof. Dr.sc. Martin J. Dürst
Department of Intelligent Information Technology
College of Science and Engineering
Aoyama Gakuin University
Fuchinobe 5-1-10, Chuo-ku, Sagamihara
252-5258 Japan

---

From: Sanjay Dalal <[email-masked]>
Date: Wed, 26 May 2021 06:15:46 -0700

Hello Martin,

Thank you for your comments. We would incorporate your suggestions.

regards,
sanjay

On Tue, May 25, 2021 at 12:26 AM Martin J. Dürst <[email-masked]>
wrote:

> > Field <https://datatracker.ietf.org/doc/html/draft-idempotency-header-01
> >
> https://developer.squareup.com/docs/build-basics/using-
> >        rest-api
> >