Re: [httpapi] Header for idempotency

[Sanjay Dalal <[e-mail]>]

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 <[e-mail]>
wrote:

> 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.
>
> On 2021-05-25 14:11, Sanjay Dalal wrote:
> > 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
> >
> >
>
> --
> 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
>