Re: [httpapi] Header for idempotency

["Martin J. Dürst" <[e-mail]>]

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