draft-ietf-appsawg-http-problem-03.txt		draft-ietf-appsawg-http-problem-latest.txt
	Network Working Group M. Nottingham		Network Working Group M. Nottingham
	Internet-Draft Akamai		Internet-Draft Akamai
	Intended status: Standards Track E. Wilde		Intended status: Standards Track E. Wilde
	Expires: July 29, 2016 January 26, 2016		Expires: January 7, 2025 July 6, 2024
	Problem Details for HTTP APIs		Problem Details for HTTP APIs
	draft-ietf-appsawg-http-problem-03		draft-ietf-appsawg-http-problem-03
	Abstract		Abstract
	This document defines a "problem detail" as a way to carry machine-		This document defines a "problem detail" as a way to carry machine-
	readable details of errors in a HTTP response, to avoid the need to		readable details of errors in a HTTP response, to avoid the need to
	define new error response formats for HTTP APIs.		define new error response formats for HTTP APIs.
	skipping to change at page 1, line 30 ¶		skipping to change at page 1, line 30 ¶
	This section is to be removed before publication.		This section is to be removed before publication.
	Note to RFC Editor		Note to RFC Editor
	Please replace all occurrences of "XXXX" with the final RFC number		Please replace all occurrences of "XXXX" with the final RFC number
	chosen for this draft.		chosen for this draft.
	This section is to be removed before publication.		This section is to be removed before publication.
	Status of this Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	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 http://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 July 29, 2016.		This Internet-Draft will expire on January 7, 2025.
	Copyright Notice		Copyright Notice
	Copyright (c) 2016 IETF Trust and the persons identified as the		Copyright (c) 2024 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
	(http://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 . . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4		3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4
	3.1. Problem Details Object Members . . . . . . . . . . . . . . 5		3.1. Problem Details Object Members . . . . . . . . . . . . . 5
	3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6		3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6
	4. Defining New Problem Types . . . . . . . . . . . . . . . . . . 7		4. Defining New Problem Types . . . . . . . . . . . . . . . . . 7
	4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8		4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8
	4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 8		4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 8
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 9		5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
	7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10		7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11
	8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11		8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
	8.1. Normative References . . . . . . . . . . . . . . . . . . . 11		8.1. Normative References . . . . . . . . . . . . . . . . . . 11
	8.2. Informative References . . . . . . . . . . . . . . . . . . 11		8.2. Informative References . . . . . . . . . . . . . . . . . 12
	Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . . 12		8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 13
	Appendix B. Using Problem Details with Other Formats . . . . . . 14		Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 13
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15		Appendix B. Using Problem Details with Other Formats . . . . . . 15
			Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
	1. Introduction		1. Introduction
	HTTP [RFC7230] status codes are sometimes not sufficient to convey		HTTP [RFC7230] status codes are sometimes not sufficient to convey
	enough information about an error to be helpful. While humans behind		enough information about an error to be helpful. While humans behind
	Web browsers can be informed about the nature of the problem with an		Web browsers can be informed about the nature of the problem with an
	HTML [W3C.REC-html5-20141028] response body, non-human consumers of		HTML [W3C.REC-html5-20141028] response body, non-human consumers of
	so-called "HTTP APIs" are usually not.		so-called "HTTP APIs" are usually not.
	This specification defines simple JSON [RFC7159] and XML		This specification defines simple JSON [RFC7159] and XML
	skipping to change at page 9, line 40 ¶		skipping to change at page 9, line 44 ¶
	As such, those defining problem types as well as generators and		As such, those defining problem types as well as generators and
	consumers of problems need to be aware that generic software (such as		consumers of problems need to be aware that generic software (such as
	proxies, load balancers, firewalls, virus scanners) are unlikely to		proxies, load balancers, firewalls, virus scanners) are unlikely to
	know of or respect the status code conveyed in this member.		know of or respect the status code conveyed in this member.
	6. IANA Considerations		6. IANA Considerations
	This specification defines two new Internet media types [RFC6838]:		This specification defines two new Internet media types [RFC6838]:
	Type name: application		Type name: application
	Subtype name: problem+json		Subtype name: problem+json
	Required parameters: None		Required parameters: None
	Optional parameters: None; unrecognised parameters should be ignored		Optional parameters: None; unrecognised parameters should be ignored
	Encoding considerations: Same as [RFC7159]		Encoding considerations: Same as [RFC7159]
	Security considerations: see Section 5 of this document		Security considerations: see Section 5 of this document
	Interoperability considerations: None		Interoperability considerations: None
	Published specification: [this document]		Published specification: [this document]
	Applications that use this media type: HTTP		Applications that use this media type: HTTP
	Fragment identifier considerations: Same as for application/json		Fragment identifier considerations: Same as for application/json
	([RFC7159])		([RFC7159])
	Additional information:		Additional information:
	Deprecated alias names for this type: n/a		Deprecated alias names for this type: n/a
	Magic number(s): n/a		Magic number(s): n/a
	File extension(s): n/a		File extension(s): n/a
	Macintosh file type code(s): n/a		Macintosh file type code(s): n/a
	Person and email address to contact for further information: Mark
	Nottingham <mnot@mnot.net>		Person and email address to contact for further information: Mark No
			ttingham <mnot@mnot.net>
	Intended usage: COMMON		Intended usage: COMMON
	Restrictions on usage: None.		Restrictions on usage: None.
	Author: Mark Nottingham <mnot@mnot.net>		Author: Mark Nottingham <mnot@mnot.net>
	Change controller: IESG		Change controller: IESG
	Type name: application		Type name: application
	Subtype name: problem+xml		Subtype name: problem+xml
	Required parameters: None		Required parameters: None
	Optional parameters: None; unrecognised parameters should be ignored		Optional parameters: None; unrecognised parameters should be ignored
	Encoding considerations: Same as [RFC7303]		Encoding considerations: Same as [RFC7303]
	Security considerations: see Section 5 of this document		Security considerations: see Section 5 of this document
	Interoperability considerations: None		Interoperability considerations: None
	Published specification: [this document]		Published specification: [this document]
	Applications that use this media type: HTTP		Applications that use this media type: HTTP
	Fragment identifier considerations: Same as for application/xml (as		Fragment identifier considerations: Same as for application/xml (as
	specified by Section 5 of [RFC7303])		specified by Section 5 of [RFC7303])
	Additional information:		Additional information:
	Deprecated alias names for this type: n/a		Deprecated alias names for this type: n/a
	Magic number(s): n/a		Magic number(s): n/a
	File extension(s): n/a		File extension(s): n/a
	Macintosh file type code(s): n/a		Macintosh file type code(s): n/a
	Person and email address to contact for further information: Mark
	Nottingham <mnot@mnot.net>		Person and email address to contact for further information: Mark No
			ttingham <mnot@mnot.net>
	Intended usage: COMMON		Intended usage: COMMON
	Restrictions on usage: None.		Restrictions on usage: None.
	Author: Mark Nottingham <mnot@mnot.net>		Author: Mark Nottingham <mnot@mnot.net>
	Change controller: IESG		Change controller: IESG
	7. Acknowledgements		7. Acknowledgements
	The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu		The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu
	Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall,		Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall,
	Julian Reschke, and James Snell for review of this specification.		Julian Reschke, and James Snell for review of this specification.
	8. References		8. References
	8.1. Normative References		8.1. Normative References
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/		Requirement Levels", BCP 14, RFC 2119,
	RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform		[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
	Resource Identifier (URI): Generic Syntax", STD 66,		Resource Identifier (URI): Generic Syntax", STD 66,
	RFC 3986, DOI 10.17487/RFC3986, January 2005,		RFC 3986, DOI 10.17487/RFC3986, January 2005,
	<https://www.rfc-editor.org/info/rfc3986>.		<https://www.rfc-editor.org/info/rfc3986>.
	[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax		[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
	Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/		Specifications: ABNF", STD 68, RFC 5234,
	RFC5234, January 2008,		DOI 10.17487/RFC5234, January 2008,
	<https://www.rfc-editor.org/info/rfc5234>.		<https://www.rfc-editor.org/info/rfc5234>.
	[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data		[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
	Interchange Format", RFC 7159, DOI 10.17487/RFC7159,		Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
	March 2014, <https://www.rfc-editor.org/info/rfc7159>.		2014, <https://www.rfc-editor.org/info/rfc7159>.
	[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Message Syntax and Routing",		Protocol (HTTP/1.1): Message Syntax and Routing",
	RFC 7230, DOI 10.17487/RFC7230, June 2014,		RFC 7230, DOI 10.17487/RFC7230, June 2014,
	<https://www.rfc-editor.org/info/rfc7230>.		<https://www.rfc-editor.org/info/rfc7230>.
	[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Semantics and Content", RFC 7231,		Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
	DOI 10.17487/RFC7231, June 2014,		DOI 10.17487/RFC7231, June 2014,
	<https://www.rfc-editor.org/info/rfc7231>.		<https://www.rfc-editor.org/info/rfc7231>.
	[W3C.REC-xml-20081126]		[W3C.REC-xml-20081126]
	"Extensible Markup Language (XML) 1.0 (Fifth Edition)",		Maler, E., Ed., Yergeau, F., Ed., Paoli, J., Ed.,
	W3C REC REC-xml-20081126, W3C REC-xml-20081126,		Sperberg-McQueen, M., Ed., and T. Bray, Ed., "Extensible
	November 2008,		Markup Language (XML) 1.0 (Fifth Edition)", W3C REC REC-
			xml-20081126, W3C REC-xml-20081126, November 2008,
	<https://www.w3.org/TR/2008/REC-xml-20081126/>.		<https://www.w3.org/TR/2008/REC-xml-20081126/>.
	8.2. Informative References		8.2. Informative References
	[ISO-19757-2]		[ISO-19757-2]
	International Organization for Standardization,		International Organization for Standardization,
	"Information Technology --- Document Schema Definition		"Information Technology --- Document Schema Definition
	Languages (DSDL) --- Part 2: Grammar-based Validation ---		Languages (DSDL) --- Part 2: Grammar-based Validation ---
	RELAX NG", ISO/IEC 19757-2, 2003.		RELAX NG", ISO/IEC 19757-2, 2003.
	[RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed		[RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed
	Authoring and Versioning (WebDAV)", RFC 4918,		Authoring and Versioning (WebDAV)", RFC 4918,
	DOI 10.17487/RFC4918, June 2007,		DOI 10.17487/RFC4918, June 2007,
	<https://www.rfc-editor.org/info/rfc4918>.		<https://www.rfc-editor.org/info/rfc4918>.
	[RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/		[RFC5988] Nottingham, M., "Web Linking", RFC 5988,
	RFC5988, October 2010,		DOI 10.17487/RFC5988, October 2010,
	<https://www.rfc-editor.org/info/rfc5988>.		<https://www.rfc-editor.org/info/rfc5988>.
	[RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694,		[RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694,
	DOI 10.17487/RFC6694, August 2012,		DOI 10.17487/RFC6694, August 2012,
	<https://www.rfc-editor.org/info/rfc6694>.		<https://www.rfc-editor.org/info/rfc6694>.
	[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type		[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
	Specifications and Registration Procedures", BCP 13,		Specifications and Registration Procedures", BCP 13,
	RFC 6838, DOI 10.17487/RFC6838, January 2013,		RFC 6838, DOI 10.17487/RFC6838, January 2013,
	<https://www.rfc-editor.org/info/rfc6838>.		<https://www.rfc-editor.org/info/rfc6838>.
	[RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,		[RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,
	DOI 10.17487/RFC7303, July 2014,		DOI 10.17487/RFC7303, July 2014,
	<https://www.rfc-editor.org/info/rfc7303>.		<https://www.rfc-editor.org/info/rfc7303>.
	[W3C.REC-html5-20141028]		[W3C.REC-html5-20141028]
	"HTML5", W3C REC REC-html5-20141028, W3C REC-html5-		Navara, E. D., Ed., Hickson, I., Ed., Berjon, R., Ed.,
	20141028, October 2014,		Pfeiffer, S., Ed., Faulkner, S., Ed., O'Connor, T., Ed.,
			and T. Leithead, Ed., "HTML5", W3C REC REC-html5-20141028,
			W3C REC-html5-20141028, October 2014,
	<https://www.w3.org/TR/2014/REC-html5-20141028/>.		<https://www.w3.org/TR/2014/REC-html5-20141028/>.
	[W3C.REC-rdfa-core-20130822]		[W3C.REC-rdfa-core-20130822]
	"RDFa Core 1.1 - Second Edition", W3C REC REC-rdfa-core-		Adida, B., Ed., Herman, I., Ed., Birbeck, M., Ed., and S.
	20130822, W3C REC-rdfa-core-20130822, August 2013,		McCarron, Ed., "RDFa Core 1.1 - Second Edition", W3C REC
			REC-rdfa-core-20130822, W3C REC-rdfa-core-20130822, August
			2013,
	<https://www.w3.org/TR/2013/REC-rdfa-core-20130822/>.		<https://www.w3.org/TR/2013/REC-rdfa-core-20130822/>.
	[W3C.REC-xml-stylesheet-20101028]		[W3C.REC-xml-stylesheet-20101028]
			Thompson, H., Ed., Clark, J., Ed., and S. Pieters, Ed.,
	"Associating Style Sheets with XML documents 1.0 (Second		"Associating Style Sheets with XML documents 1.0 (Second
	Edition)", W3C REC REC-xml-stylesheet-20101028, W3C REC-		Edition)", W3C REC REC-xml-stylesheet-20101028, W3C REC-
	xml-stylesheet-20101028, October 2010,		xml-stylesheet-20101028, October 2010,
	<https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028/>.		<https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028/>.
	URIs		8.3. URIs
	[1] <https://www.ietf.org/mailman/listinfo/apps-discuss>		[1] https://www.ietf.org/mailman/listinfo/apps-discuss
	Appendix A. HTTP Problems and XML		Appendix A. HTTP Problems and XML
	Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary		Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary
	format convention. Such APIs can express problem details using the		format convention. Such APIs can express problem details using the
	format defined in this appendix.		format defined in this appendix.
	The RELAX NG schema [ISO-19757-2] for the XML format is as follows.		The RELAX NG schema [ISO-19757-2] for the XML format is as follows.
	Keep in mind that this schema is only meant as documentation, and not		Keep in mind that this schema is only meant as documentation, and not
	as a normative schema that captures all constraints of the XML		as a normative schema that captures all constraints of the XML
End of changes. 52 change blocks.
	44 lines changed or deleted		88 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/