draft-ietf-httpapi-idempotency-key-header-06.unpg.txt		draft-ietf-httpapi-idempotency-key-header-latest.txt
	Network Working Group J. Jena		Network Working Group J. Jena
	Internet-Draft		Internet-Draft
	Intended status: Standards Track S. Dalal		Intended status: Standards Track S. Dalal
	Expires: August 28, 2025 February 24, 2025		Expires: November 22, 2025 May 21, 2025
	The Idempotency-Key HTTP Header Field		The Idempotency-Key HTTP Header Field
	draft-ietf-httpapi-idempotency-key-header-06		draft-ietf-httpapi-idempotency-key-header-latest
	Abstract		Abstract
	The HTTP Idempotency-Key request header field can be used to make		The HTTP Idempotency-Key request header field can be used to make
	non-idempotent HTTP methods such as "POST" or "PATCH" fault-tolerant.		non-idempotent HTTP methods such as "POST" or "PATCH" fault-tolerant.
	About This Document		About This Document
	This note is to be removed before publishing as an RFC.		This note is to be removed before publishing as an RFC.
	skipping to change at line 47 ¶		skipping to change at page 1, line 48 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on August 28, 2025.		This Internet-Draft will expire on November 22, 2025.
	Copyright Notice		Copyright Notice
	Copyright (c) 2025 IETF Trust and the persons identified as the		Copyright (c) 2025 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents		Provisions Relating to IETF Documents
	(https://trustee.ietf.org/license-info) in effect on the date of		(https://trustee.ietf.org/license-info) in effect on the date of
	publication of this document. Please review these documents		publication of this document. Please review these documents
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	described in the Simplified BSD License.		described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	1.1. Notational Conventions		1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
	2. The Idempotency-Key HTTP Request Header Field		2. The Idempotency-Key HTTP Request Header Field . . . . . . . . 3
	2.1. Syntax		2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3
	2.2. Uniqueness of Idempotency Key		2.2. Uniqueness of Idempotency Key . . . . . . . . . . . . . . 3
	2.3. Idempotency Key Validity and Expiry		2.3. Idempotency Key Validity and Expiry . . . . . . . . . . . 4
	2.4. Idempotency Fingerprint		2.4. Idempotency Fingerprint . . . . . . . . . . . . . . . . . 4
	2.5. Responsibilities		2.5. Responsibilities . . . . . . . . . . . . . . . . . . . . 4
	2.5.1. Client		2.5.1. Client . . . . . . . . . . . . . . . . . . . . . . . 4
	2.5.2. Resource		2.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 5
	2.6. Idempotency Enforcement		2.6. Idempotency Enforcement . . . . . . . . . . . . . . . . . 5
	2.7. Error Handling		2.7. Error Handling . . . . . . . . . . . . . . . . . . . . . 5
	3. IANA Considerations		3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
	3.1. The Idempotency-Key HTTP Request Header Field		3.1. The Idempotency-Key HTTP Request Header Field . . . . . . 7
	4. Implementation Status		4. Implementation Status . . . . . . . . . . . . . . . . . . . . 7
	4.1. Implementing the Concept		4.1. Implementing the Concept . . . . . . . . . . . . . . . . 9
	5. Security Considerations		5. Security Considerations . . . . . . . . . . . . . . . . . . . 11
	6. Examples		6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 12
	7. References		7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
	7.1. Normative References		7.1. Normative References . . . . . . . . . . . . . . . . . . 12
	7.2. Informative References		7.2. Informative References . . . . . . . . . . . . . . . . . 13
	Acknowledgments		Appendix A. Changes from Draft-05 . . . . . . . . . . . . . . . 13
	Authors' Addresses		Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 13
			Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
	1. Introduction		1. Introduction
	In mathematics and computer science, an idempotent operation is one		In mathematics and computer science, an idempotent operation is one
	that can be applied multiple times without changing the result beyond		that can be applied multiple times without changing the result beyond
	the initial application. It does not matter if the operation is		the initial application. It does not matter if the operation is
	called only once or tens of times over.		called only once or tens of times over.
	Idempotency is important in building fault-tolerant HTTP APIs. An		Idempotency is important in building fault-tolerant HTTP APIs. An
	HTTP request method is considered "idempotent" if the intended effect		HTTP request method is considered "idempotent" if the intended effect
	on the server of multiple identical requests with that method is the		on the server of multiple identical requests with that method is the
	same as the effect for a single such request. Per [RFC9110], the		same as the effect for a single such request. Per [RFC9110], the
	methods "OPTIONS", "HEAD", "GET", "PUT" and "DELETE" are idempotent		methods "OPTIONS", "HEAD", "GET", "PUT" and "DELETE" are idempotent
	while methods "POST" and "PATCH" are not.		while methods "POST" and "PATCH" are not.
	Let's say a client of an HTTP API wants to create (or update) a		Let's say a client of an HTTP API wants to create (or update) a
	resource using a "POST" method. Repeating the request multiple times		resource using a "POST" method. Repeating the request multiple times
	can result in duplication or incorrect updates. Consider a scenario		can result in duplication or incorrect updates. Consider a scenario
	where the client sent a "POST" request to the server, but the request		where the client sent a "POST" request to the server, but the request
	timed out. The client does not know if the resource was created (or		timed out. The client is left uncertain about the status of the
	updated), because it does not know when the timeout occured from the		resource. It doesn't know if the resource was created or updated, or
	server's perspective. Furthermore, the client does not know if it		if the server even completed processing the request. Furthermore,
	can safely retry the request.		the client does not know if it can safely retry the request.
	1.1. Notational Conventions		1.1. Notational Conventions
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in		"OPTIONAL" in this document are to be interpreted as described in
	BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all		BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	This specification uses the Augmented Backus-Naur Form (ABNF)		This specification uses the Augmented Backus-Naur Form (ABNF)
	skipping to change at line 429 ¶		skipping to change at page 9, line 49 ¶
	This is a list of implementations that implement the general concept,		This is a list of implementations that implement the general concept,
	but do so using different mechanisms:		but do so using different mechanisms:
	Organization: Django		Organization: Django
	o Description: Django uses custom HTTP header named		o Description: Django uses custom HTTP header named
	"HTTP_IDEMPOTENCY_KEY"		"HTTP_IDEMPOTENCY_KEY"
	o Reference: https://pypi.org/project/django-idempotency-key		o Reference: https://pypi.org/project/django-idempotency-key
			Organization: Chargebee
			o Description: Chargebee uses custom HTTP header named "chargebee-
			idempotency-key"
			o Reference: https://apidocs.chargebee.com/docs/api/idempotency
	Organization: Twilio		Organization: Twilio
	o Description: Twilio uses custom HTTP header named "I-Twilio-		o Description: Twilio uses custom HTTP header named "I-Twilio-
	Idempotency-Token" in webhooks		Idempotency-Token" in webhooks
	o Reference: https://www.twilio.com/docs/usage/webhooks/webhooks-		o Reference: https://www.twilio.com/docs/usage/webhooks/webhooks-
	connection-overrides		connection-overrides
	Organization: PayPal		Organization: PayPal
	skipping to change at line 600 ¶		skipping to change at page 13, line 34 ¶
	7.3. URIs		7.3. URIs
	[1] https://github.com/paypal/api-standards/blob/master/		[1] https://github.com/paypal/api-standards/blob/master/
	patterns.md#idempotency		patterns.md#idempotency
	[2] https://stripe.com/docs/idempotency		[2] https://stripe.com/docs/idempotency
	[3] https://tools.ietf.org/html/draft-nottingham-http-poe-00		[3] https://tools.ietf.org/html/draft-nottingham-http-poe-00
			Appendix A. Changes from Draft-05
			This revision has made the following changes: * Added change log
			starting from previous draft * Correction in introduction * Added an
			implementer
	Acknowledgments		Acknowledgments
	The authors would like to thank Mark Nottingham for his support for		The authors would like to thank Mark Nottingham for his support for
	this Internet Draft. We would like to acknowledge that this draft is		this Internet Draft. We would like to acknowledge that this draft is
	inspired by Idempotency related patterns described in API		inspired by Idempotency related patterns described in API
	documentation of PayPal [1] and Stripe [2] as well as Internet Draft		documentation of PayPal [1] and Stripe [2] as well as Internet Draft
	on POST Once Exactly [3] authored by Mark Nottingham.		on POST Once Exactly [3] authored by Mark Nottingham.
	The authors take all responsibility for errors and omissions.		The authors take all responsibility for errors and omissions.
End of changes. 7 change blocks.
	30 lines changed or deleted		44 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/