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: December 15, 2018 June 13, 2018
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 December 15, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2018 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>.
skipping to change at page 12, line 7 skipping to change at page 12, line 44
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]
Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
Navara, E., O&#039;Connor, T., and S. Pfeiffer, "HTML5", Navara, E., O&#039;Connor, T., and S. Pfeiffer, "HTML5",
World Wide Web Consortium Recommendation REC-html5- World Wide Web Consortium Recommendation REC-
20141028, October 2014, html5-20141028, October 2014,
<http://www.w3.org/TR/2014/REC-html5-20141028>. <http://www.w3.org/TR/2014/REC-html5-20141028>.
[W3C.REC-rdfa-core-20130822] [W3C.REC-rdfa-core-20130822]
Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa
Core 1.1 - Second Edition", World Wide Web Consortium Core 1.1 - Second Edition", World Wide Web Consortium
Recommendation REC-rdfa-core-20130822, August 2013, Recommendation REC-rdfa-core-20130822, August 2013,
<http://www.w3.org/TR/2013/REC-rdfa-core-20130822>. <http://www.w3.org/TR/2013/REC-rdfa-core-20130822>.
[W3C.REC-xml-stylesheet-20101028] [W3C.REC-xml-stylesheet-20101028]
Clark, J., Pieters, S., and H. Thompson, "Associating Clark, J., Pieters, S., and H. Thompson, "Associating
Style Sheets with XML documents 1.0 (Second Edition)", Style Sheets with XML documents 1.0 (Second Edition)",
World Wide Web Consortium Recommendation REC-xml- World Wide Web Consortium Recommendation REC-xml-
stylesheet-20101028, October 2010, stylesheet-20101028, October 2010,
<http://www.w3.org/TR/2010/REC-xml-stylesheet-20101028>. <http://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. 49 change blocks. 
39 lines changed or deleted 77 lines changed or added

This html diff was produced by rfcdiff 1.44jr. The latest version is available from http://tools.ietf.org/tools/rfcdiff/