draft-idempotency-header-01.xml

<?xml version="1.0" encoding="utf-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.3.15 -->

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>

<rfc ipr="trust200902" docName="draft-idempotency-header-01" category="std">

  <front>
    <title>The Idempotency HTTP Header Field</title>

    <author initials="J." surname="Jena" fullname="Jayadeba Jena">
      <organization>PayPal, Inc.</organization>
      <address>
        <email>jjena@paypal.com</email>
      </address>
    </author>
    <author initials="S." surname="Dalal" fullname="Sanjay Dalal">
      <organization></organization>
      <address>
        <email>sanjay.dalal@cal.berkeley.edu</email>
        <uri>https://github.com/sdatspun2</uri>
      </address>
    </author>

    <date year="2020" month="November" day="23"/>

    
    
    

    <abstract>


<t>The <spanx style="verb">HTTP</spanx> Idempotency request header field can be used to carry idempotency key in order to make non-idempotent <spanx style="verb">HTTP</spanx> methods such as <spanx style="verb">POST</spanx> or <spanx style="verb">PATCH</spanx> fault-tolerant.</t>



    </abstract>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>Idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application. It does not matter if the operation is called only once, or 10s of times over. The result <spanx style="verb">SHOULD</spanx> be the same.</t>

<t>Idempotency is important in building a fault-tolerant <spanx style="verb">HTTP API</spanx>. An <spanx style="verb">HTTP</spanx> request method is considered <spanx style="verb">idempotent</spanx> if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request. According to <xref target="RFC7231"/>, <spanx style="verb">HTTP</spanx> methods <spanx style="verb">OPTIONS</spanx>, <spanx style="verb">HEAD</spanx>, <spanx style="verb">GET</spanx>, <spanx style="verb">PUT</spanx> and <spanx style="verb">DELETE</spanx> are idempotent while methods <spanx style="verb">POST</spanx> and <spanx style="verb">PATCH</spanx> are not.</t>

<t>Let’s say a client of an <spanx style="verb">HTTP API</spanx> wants to create (or update) a resource using a <spanx style="verb">POST</spanx> method. Since <spanx style="verb">POST</spanx> is <spanx style="verb">NOT</spanx> an idempotent method, calling it multiple times can result in duplication or wrong updates. Consider a scenario where the client sent a <spanx style="verb">POST</spanx> request to the server, but it got a timeout. Following questions arise :  Is the resource actually created (or updated)? Did the timeout occur during sending of the request, or when receiving of the response? Can the client safely retry the request, or does it need to figure out what happened in the first place? If <spanx style="verb">POST</spanx> had been an idempotent method, such questions may not arise. Client would safely retry a request until it actually gets a valid response from the server.</t>

<t>For many use cases of <spanx style="verb">HTTP API</spanx>, duplicate resource is a severe problem from business perspective. For example, duplicate records for requests involving any kind of money transfer <spanx style="verb">MUST NOT</spanx> be allowed. In other cases, processing of duplicate webhook delivery is not expected.</t>

<section anchor="notational-conventions" title="Notational Conventions">

<t>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 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they appear in all capitals, as shown here.</t>

<t>This specification uses the Augmented Backus-Naur Form (ABNF) notation of <xref target="RFC5234"/> and includes, by reference, the IMF-fixdate rule as defined in Section 7.1.1.1 of <xref target="RFC7231"/>.</t>

<t>The term “resource” is to be interpreted as defined in Section 2 of <xref target="RFC7231"/>, that is identified by an URI. The term “resource server” is to be interpreted as “origin server” as defined in Section 3 of <xref target="RFC7231"/>.</t>

</section>
</section>
<section anchor="the-idempotency-http-request-header-field" title="The Idempotency HTTP Request Header Field">

<t>An idempotency key is a unique value generated by the client which the resource server uses to recognize subsequent retries of the same request. The <spanx style="verb">Idempotency-Key</spanx> HTTP request header field carries this key.</t>

<section anchor="syntax" title="Syntax">

<t>The <spanx style="verb">Idempotency-Key</spanx> request header field describes</t>

<figure><artwork><![CDATA[
Idempotency-Key       = idempotency-key-value

idempotency-key-value = opaque-value
opaque-value          = DQUOTE *idempotencyvalue DQUOTE
idempotencyvalue      = %x21 / %x23-7E / obs-text
       ; VCHAR except double quotes, plus obs-text
]]></artwork></figure>

<t>Clients MUST NOT include more than one <spanx style="verb">Idempotency-Key</spanx> header field in the same request.</t>

<t>The following example shows an idempotency key using <spanx style="verb">UUID</spanx> <xref target="RFC4122"/>:</t>

<figure><artwork><![CDATA[
Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"
]]></artwork></figure>

</section>
<section anchor="uniqueness-of-idempotency-key" title="Uniqueness of Idempotency Key">

<t>The idempotency key that is supplied as part of every <spanx style="verb">POST</spanx> request MUST be unique and <spanx style="verb">MUST</spanx> not be reused with another request with a different request payload.</t>

<t>Uniqueness of the key <spanx style="verb">MUST</spanx> be defined by the resource owner and <spanx style="verb">MUST</spanx> be implemented by the clients of the resource server. It is <spanx style="verb">RECOMMENDED</spanx> that <spanx style="verb">UUID</spanx> <xref target="RFC4122"/> or a similar random identifier be used as an idempotency key.</t>

</section>
<section anchor="idempotency-key-validity-and-expiry" title="Idempotency Key Validity and Expiry">

<t>The resource MAY enforce time based idempotency keys, thus, be able to purge or delete a key upon its expiry. The resource server SHOULD define such expiration policy and publish in related documentation.</t>

</section>
<section anchor="idempotency-fingerprint" title="Idempotency Fingerprint">

<t>An idempotency fingerprint MAY be used in conjunction with an idempotency key to determine the uniqueness of a request. Such a fingerprint is generated from request payload data by the resource server. An idempotency fingerprint generation algorithm MAY use one of the following or similar approaches to create a fingerprint.</t>

<t><list style="symbols">
  <t>Checksum of the entire request payload.</t>
  <t>Checksum of selected element(s) in the request payload.</t>
  <t>Field value match for each field in the request payload.</t>
  <t>Field value match for selected element(s) in the request payload.</t>
  <t>Request digest/signature.</t>
</list></t>

</section>
<section anchor="responsibilities" title="Responsibilities">

<t>Client</t>

<t>Clients of <spanx style="verb">HTTP API</spanx> requiring idempotency, SHOULD understand the idempotency related requirements as published by the server and use appropriate algorithm to generate idempotency keys.</t>

<t>For each request, client SHOULD</t>

<t><list style="symbols">
  <t>Send a unique idempotency key in the HTTP <spanx style="verb">Idempotency-Key</spanx> request header field.</t>
</list></t>

<t>Resource Server</t>

<t>Resource server MUST publish idempotency related specification. This specification MUST include expiration related policy if applicable. Server is responsible for managing the lifecycle of the idempotency key.</t>

<t>For each request, server SHOULD</t>

<t><list style="symbols">
  <t>Identify idempotency key from the HTTP <spanx style="verb">Idempotency-Key</spanx> request header field.</t>
  <t>Generate idempotency fingerprint if required.</t>
  <t>Check for idempotency considering various scenarios including the ones described in section below.</t>
</list></t>

</section>
<section anchor="idempotency-enforcement-scenarios" title="Idempotency Enforcement Scenarios">

<t><list style="symbols">
  <t>First time request (idempotency key or fingerprint has not been seen)  <vspace blankLines='1'/>
The resource server SHOULD process the request normally and respond with an appropriate response and status code.</t>
  <t>Duplicate request (idempotency key or fingerprint has been seen)  <vspace blankLines='1'/>
Retry  <vspace blankLines='1'/>
The request was retried after the original request completed. The resource server MUST respond with the result of the previously completed operation, success or an error.  <vspace blankLines='1'/>
Concurrent Request  <vspace blankLines='1'/>
The request was retried before the original request completed. The resource server MUST respond with a resource conflict error. See Error Scenarios for details.</t>
</list></t>

</section>
<section anchor="error-scenarios" title="Error Scenarios">

<t>If the <spanx style="verb">Idempotency-Key</spanx> request header is missing for a documented idempotent operation requiring this header, the resource server MUST reply with an <spanx style="verb">HTTP</spanx> <spanx style="verb">400</spanx> status code with body containing a link pointing to relevant documentation. Alternately, using the <spanx style="verb">HTTP</spanx> header <spanx style="verb">Link</spanx>, the client can be informed about the error as shown below.</t>

<figure><artwork><![CDATA[
HTTP/1.1 400 Bad Request
Link: <https://developer.example.com/idempotency>;
  rel="describedby"; type="text/html"
]]></artwork></figure>

<t>If there is an attempt to reuse an idempotency key with a different request payload, the resource server MUST reply with a <spanx style="verb">HTTP</spanx> <spanx style="verb">422</spanx> status code with body containing a link pointing to relevant documentation. The status code <spanx style="verb">422</spanx> is defined in Section 11.2 of <xref target="RFC4918"/>. The server can also inform the client by using the <spanx style="verb">HTTP</spanx> header <spanx style="verb">Link</spanx> as shown below.</t>

<figure><artwork><![CDATA[
HTTP/1.1 422 Unprocessable Entity
Link: <https://developer.example.com/idempotency>;
rel="describedby"; type="text/html"
]]></artwork></figure>

<t>If the request is retried, while the original request is still being processed, the resource server MUST reply with an <spanx style="verb">HTTP</spanx> <spanx style="verb">409</spanx> status code with body containing a link or the <spanx style="verb">HTTP</spanx> header <spanx style="verb">Link</spanx> pointing to the relevant documentation.</t>

<figure><artwork><![CDATA[
HTTP/1.1 409 Conflict
Link: <https://developer.example.com/idempotency>;
rel="describedby"; type="text/html"
]]></artwork></figure>

<t>For other errors, the resource MUST return the appropriate status code and error message.</t>

</section>
</section>
<section anchor="iana-considerations" title="IANA Considerations">

<section anchor="the-idempotency-key-http-request-header-field" title="The Idempotency-Key HTTP Request Header Field">

<t>The <spanx style="verb">Idempotency-Key</spanx> request header should be added to the permanent registry of message header fields (see <xref target="RFC3864"/>), taking into account the guidelines given by HTTP/1.1 <xref target="RFC7231"/>.</t>

<figure><artwork><![CDATA[
Header Field Name: Idempotency-Key

Applicable Protocol: Hypertext Transfer Protocol (HTTP)

Status: Standard

Authors:
        Jayadeba Jena
        Email: jjena@paypal.com


        Sanjay Dalal
        Email: sanjay.dalal@cal.berkeley.edu

Change controller: IETF

Specification document: this specification,
            Section 2 "The Idempotency HTTP Request Header Field"
]]></artwork></figure>

</section>
</section>
<section anchor="implementation-status" title="Implementation Status">

<t>Note to RFC Editor: Please remove this section before publication.</t>

<t>This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in <xref target="RFC7942"/>.  The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs.  Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors.  This is not intended as, and must not be construed to be, a catalog of available implementations or their features.  Readers are advised to note that
other implementations may exist.</t>

<t>According to RFC 7942, “this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit”.</t>

<t>Organization: Stripe</t>

<t><list style="symbols">
  <t>Description: Stripe uses custom HTTP header named <spanx style="verb">Idempotency-Key</spanx></t>
  <t>Reference:  https://stripe.com/docs/idempotency</t>
</list></t>

<t>Organization: Adyen</t>

<t><list style="symbols">
  <t>Description: Adyen uses custom HTTP header named <spanx style="verb">Idempotency-Key</spanx></t>
  <t>Reference: https://docs.adyen.com/development-resources/api-idempotency/</t>
</list></t>

<t>Organization: Dwolla</t>

<t><list style="symbols">
  <t>Description: Dwolla uses custom HTTP header named <spanx style="verb">Idempotency-Key</spanx></t>
  <t>Reference: https://docs.dwolla.com/</t>
</list></t>

<t>Organization: Interledger</t>

<t><list style="symbols">
  <t>Description: Interledger uses custom HTTP header named <spanx style="verb">Idempotency-Key</spanx></t>
  <t>Reference: https://github.com/interledger/</t>
</list></t>

<t>Organization: WorldPay</t>

<t><list style="symbols">
  <t>Description: WorldPay uses custom HTTP header named <spanx style="verb">Idempotency-Key</spanx></t>
  <t>Reference: https://developer.worldpay.com/docs/wpg/idempotency</t>
</list></t>

<t>Organization: Yandex</t>

<t><list style="symbols">
  <t>Description: Yandex uses custom HTTP header named <spanx style="verb">Idempotency-Key</spanx></t>
  <t>Reference: https://cloud.yandex.com/docs/api-design-guide/concepts/idempotency</t>
</list></t>

<section anchor="implementing-the-concept" title="Implementing the Concept">

<t>This is a list of implementations that implement the general concept, but do so using different mechanisms:</t>

<t>Organization: Django</t>

<t><list style="symbols">
  <t>Description: Django uses custom HTTP header named <spanx style="verb">HTTP_IDEMPOTENCY_KEY</spanx></t>
  <t>Reference:  https://pypi.org/project/django-idempotency-key</t>
</list></t>

<t>Organization: Twilio</t>

<t><list style="symbols">
  <t>Description: Twilio uses custom HTTP header named <spanx style="verb">I-Twilio-Idempotency-Token</spanx> in webhooks</t>
  <t>Reference: https://www.twilio.com/docs/usage/webhooks/webhooks-connection-overrides</t>
</list></t>

<t>Organization: PayPal</t>

<t><list style="symbols">
  <t>Description: PayPal uses custom HTTP header named <spanx style="verb">PayPal-Request-Id</spanx></t>
  <t>Reference:  https://developer.paypal.com/docs/business/develop/idempotency</t>
</list></t>

<t>Organization: RazorPay</t>

<t><list style="symbols">
  <t>Description: RazorPay uses custom HTTP header named <spanx style="verb">X-Payout-Idempotency</spanx></t>
  <t>Reference: https://razorpay.com/docs/razorpayx/api/idempotency/</t>
</list></t>

<t>Organization: OpenBanking</t>

<t><list style="symbols">
  <t>Description: OpenBanking uses custom HTTP header called <spanx style="verb">x-idempotency-key</spanx></t>
  <t>Reference: https://openbankinguk.github.io/read-write-api-site3/v3.1.6/profiles/read-write-data-api-profile.html#request-headers</t>
</list></t>

<t>Organization: Square</t>

<t><list style="symbols">
  <t>Description: To make an idempotent API call, Square recommends adding a property named <spanx style="verb">idempotency_key</spanx> with a unique value in the request body.</t>
  <t>Reference: https://developer.squareup.com/docs/build-basics/using-rest-api</t>
</list></t>

<t>Organization: Google Standard Payments</t>

<t><list style="symbols">
  <t>Description: Google Standard Payments API uses a property named <spanx style="verb">requestId</spanx> in request body in order to provider idempotency in various use cases.</t>
  <t>Reference: https://developers.google.com/standard-payments/payment-processor-service-api/rest/v1/TopLevel/capture</t>
</list></t>

<t>Organization: BBVA</t>

<t><list style="symbols">
  <t>Description: BBVA Open Platform uses custom HTTP header called <spanx style="verb">X-Unique-Transaction-ID</spanx></t>
  <t>Reference: https://bbvaopenplatform.com/apiReference/APIbasics/content/x-unique-transaction-id</t>
</list></t>

<t>Organization: WebEngage</t>

<t><list style="symbols">
  <t>Description: WebEngage uses custom HTTP header called <spanx style="verb">x-request-id</spanx> to identify webhook POST requests uniquely to achieve events idempotency.</t>
  <t>Reference: https://docs.webengage.com/docs/webhooks</t>
</list></t>

</section>
</section>
<section anchor="security-considerations" title="Security Considerations">

<t>This section is meant to inform developers, information providers,
and users of known security concerns specific to the idempotency keys.</t>

<t>For idempotent request handling, the resources MAY make use of the value in the idempotency key to look up a cache or a persistent store for duplicate requests matching the key. If the resource does not validate the value of the idempotency key prior to performing such a lookup, it MAY lead to various forms of security attacks and compromise. To avoid such situations, the resource SHOULD publish the expected format of the idempotency key, algorithm used to generate it and always validate the key value as per the published specification before processing any request.</t>

</section>
<section anchor="examples" title="Examples">

<t>The first example shows an idempotency-key header field with key value using UUID version 4 scheme:</t>

<figure><artwork><![CDATA[
Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"
]]></artwork></figure>

<t>Second example shows an idempotency-key header field with key value using some random string generator:</t>

<figure><artwork><![CDATA[
Idempotency-Key: "clkyoesmbgybucifusbbtdsbohtyuuwz"
]]></artwork></figure>

</section>


  </middle>

  <back>

    <references title='Normative References'>





<reference  anchor="RFC7231" target='https://www.rfc-editor.org/info/rfc7231'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.</t></abstract>
</front>
<seriesInfo name='RFC' value='7231'/>
<seriesInfo name='DOI' value='10.17487/RFC7231'/>
</reference>



<reference  anchor="RFC2119" target='https://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>



<reference  anchor="RFC8174" target='https://www.rfc-editor.org/info/rfc8174'>
<front>
<title>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</title>
<author initials='B.' surname='Leiba' fullname='B. Leiba'><organization /></author>
<date year='2017' month='May' />
<abstract><t>RFC 2119 specifies common key words that may be used in protocol  specifications.  This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the  defined special meanings.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='8174'/>
<seriesInfo name='DOI' value='10.17487/RFC8174'/>
</reference>



<reference  anchor="RFC5234" target='https://www.rfc-editor.org/info/rfc5234'>
<front>
<title>Augmented BNF for Syntax Specifications: ABNF</title>
<author initials='D.' surname='Crocker' fullname='D. Crocker' role='editor'><organization /></author>
<author initials='P.' surname='Overell' fullname='P. Overell'><organization /></author>
<date year='2008' month='January' />
<abstract><t>Internet technical specifications often need to define a formal syntax.  Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications.  The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power.  The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges.  This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='68'/>
<seriesInfo name='RFC' value='5234'/>
<seriesInfo name='DOI' value='10.17487/RFC5234'/>
</reference>



<reference  anchor="RFC4122" target='https://www.rfc-editor.org/info/rfc4122'>
<front>
<title>A Universally Unique IDentifier (UUID) URN Namespace</title>
<author initials='P.' surname='Leach' fullname='P. Leach'><organization /></author>
<author initials='M.' surname='Mealling' fullname='M. Mealling'><organization /></author>
<author initials='R.' surname='Salz' fullname='R. Salz'><organization /></author>
<date year='2005' month='July' />
<abstract><t>This specification defines a Uniform Resource Name namespace for UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally Unique IDentifier).  A UUID is 128 bits long, and can guarantee uniqueness across space and time.  UUIDs were originally used in the Apollo Network Computing System and later in the Open Software Foundation\'s (OSF) Distributed Computing Environment (DCE), and then in Microsoft Windows platforms.</t><t>This specification is derived from the DCE specification with the kind permission of the OSF (now known as The Open Group).  Information from earlier versions of the DCE specification have been incorporated into this document.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='4122'/>
<seriesInfo name='DOI' value='10.17487/RFC4122'/>
</reference>



<reference  anchor="RFC4918" target='https://www.rfc-editor.org/info/rfc4918'>
<front>
<title>HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)</title>
<author initials='L.' surname='Dusseault' fullname='L. Dusseault' role='editor'><organization /></author>
<date year='2007' month='June' />
<abstract><t>Web Distributed Authoring and Versioning (WebDAV) consists of a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of resource properties, creation and management of resource collections, URL namespace manipulation, and resource locking (collision avoidance).</t><t>RFC 2518 was published in February 1999, and this specification obsoletes RFC 2518 with minor revisions mostly due to interoperability experience.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='4918'/>
<seriesInfo name='DOI' value='10.17487/RFC4918'/>
</reference>



<reference  anchor="RFC3864" target='https://www.rfc-editor.org/info/rfc3864'>
<front>
<title>Registration Procedures for Message Header Fields</title>
<author initials='G.' surname='Klyne' fullname='G. Klyne'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<author initials='J.' surname='Mogul' fullname='J. Mogul'><organization /></author>
<date year='2004' month='September' />
<abstract><t>This specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='90'/>
<seriesInfo name='RFC' value='3864'/>
<seriesInfo name='DOI' value='10.17487/RFC3864'/>
</reference>



<reference  anchor="RFC7230" target='https://www.rfc-editor.org/info/rfc7230'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems.  This document provides an overview of HTTP architecture and its associated terminology, defines the &quot;http&quot; and &quot;https&quot; Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.</t></abstract>
</front>
<seriesInfo name='RFC' value='7230'/>
<seriesInfo name='DOI' value='10.17487/RFC7230'/>
</reference>




    </references>

    <references title='Informative References'>





<reference  anchor="RFC7942" target='https://www.rfc-editor.org/info/rfc7942'>
<front>
<title>Improving Awareness of Running Code: The Implementation Status Section</title>
<author initials='Y.' surname='Sheffer' fullname='Y. Sheffer'><organization /></author>
<author initials='A.' surname='Farrel' fullname='A. Farrel'><organization /></author>
<date year='2016' month='July' />
<abstract><t>This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section.  This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature.</t><t>This process is not mandatory.  Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications.  This document obsoletes RFC 6982, advancing it to a Best Current Practice.</t></abstract>
</front>
<seriesInfo name='BCP' value='205'/>
<seriesInfo name='RFC' value='7942'/>
<seriesInfo name='DOI' value='10.17487/RFC7942'/>
</reference>




    </references>


<section anchor="acknowledgments" title="Acknowledgments">

<t>The authors would like to thank Mark Nottingham for his support for this Internet Draft. We would like to acknowledge that this draft is inspired by Idempotency related patterns described in API documentation of <eref target="https://github.com/paypal/api-standards/blob/master/patterns.md#idempotency">PayPal</eref> and <eref target="https://stripe.com/docs/idempotency">Stripe</eref> as well as Internet Draft on <eref target="https://tools.ietf.org/html/draft-nottingham-http-poe-00">POST Once Exactly</eref> authored by Mark Nottingham.</t>

<t>The authors take all responsibility for errors and omissions.</t>

</section>
<section anchor="appendix" title="Appendix">

<section anchor="appendix-a-imported-abnf" title="Appendix A.  Imported ABNF">

<t>The following core rules are included by reference, as defined in Appendix B.1 of <xref target="RFC5234"/>: ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII character).</t>

<t>The rules below are defined in <xref target="RFC7230"/>:</t>

<figure><artwork><![CDATA[
 obs-text      = <obs-text, see [RFC7230], Section 3.2.6>
]]></artwork></figure>

</section>
</section>


  </back>

<!-- ##markdown-source:
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
/L3zXx4NfNurOwAA

-->

</rfc>