Skip to content

Commit

Permalink
tweak note
Browse files Browse the repository at this point in the history
  • Loading branch information
@mnot
mnot committed Jul 3, 2012
1 parent b3c66e1 commit fed5020
Show file tree
Hide file tree
Showing 3 changed files with 16 additions and 16 deletions.
2 changes: 1 addition & 1 deletion http-problem/draft-nottingham-http-problem-00.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -298,7 +298,7 @@
content: normal;
}
}
</style><link rel="Contents" href="#rfc.toc"><link rel="Author" href="#rfc.authors"><link rel="Copyright" href="#rfc.copyrightnotice"><link rel="Chapter" title="1 Introduction" href="#rfc.section.1"><link rel="Chapter" title="2 Requirements" href="#rfc.section.2"><link rel="Chapter" title="3 The Problem Details JSON Object" href="#rfc.section.3"><link rel="Chapter" title="4 Expressing Problems with Link Headers" href="#rfc.section.4"><link rel="Chapter" title="5 Defining New Problem Details" href="#rfc.section.5"><link rel="Chapter" title="6 Generating Problem Details" href="#rfc.section.6"><link rel="Chapter" title="7 Consuming Problem Details" href="#rfc.section.7"><link rel="Chapter" title="8 Security Considerations" href="#rfc.section.8"><link rel="Chapter" title="9 IANA Considerations" href="#rfc.section.9"><link rel="Chapter" title="10 Acknowledgements" href="#rfc.section.10"><link rel="Chapter" href="#rfc.section.11" title="11 Normative References"><meta name="generator" content="http://greenbytes.de/tech/webdav/rfc2629.xslt, Revision 1.576, 2012-05-02 14:26:45, XSLT vendor: SAXON 9.1.0.8 from Saxonica http://www.saxonica.com/"><meta name="keywords" content="status, HTTP, error, problem"><link rel="schema.dct" href="http://purl.org/dc/terms/"><meta name="dct.creator" content="Nottingham, M."><meta name="dct.identifier" content="urn:ietf:id:draft-nottingham-http-problem-00"><meta name="dct.issued" scheme="ISO8601" content="2012-07-03"><meta name="dct.abstract" content="This specification proposes a &#34;Problem Detail&#34; as an extensible way to carry machine-readable details of HTTP errors in a response, to avoid the need to invent new response formats for non-human consumers."><meta name="description" content="This specification proposes a &#34;Problem Detail&#34; as an extensible way to carry machine-readable details of HTTP errors in a response, to avoid the need to invent new response formats for non-human consumers."></head><body><table class="header"><tbody><tr><td class="left">Network Working Group</td><td class="right">M. Nottingham</td></tr><tr><td class="left">Internet-Draft</td><td class="right">Rackspace</td></tr><tr><td class="left">Intended status: Informational</td><td class="right">July 3, 2012</td></tr><tr><td class="left">Expires: January 4, 2013</td><td class="right"></td></tr></tbody></table><p class="title">Indicating Details of Problems to Machines in HTTP<br><span class="filename">draft-nottingham-http-problem-00</span></p><h1 id="rfc.abstract"><a href="#rfc.abstract">Abstract</a></h1><p>This specification proposes a "Problem Detail" as an extensible way to carry machine-readable details of HTTP errors in a response, to avoid the need to invent new response formats for non-human consumers.</p><h1 id="rfc.note.1"><a href="#rfc.note.1">Note to Readers</a></h1><p>This specification is tentative (as all Internet-Drafts are). It's not yet clear whether defining this format will improve things enough to balance out the harm it may cause, and so it may disappear at any time. Using it before it becomes an RFC may subject you to ridicule; you have been warned.</p><p>What's the problem? In a nutshell, this sort of thing might encourage tighter coupling, making applications more brittle. On the other hand, lots of people are doing this already, so having a common way to do it -- with lots of caveats about how it can be misused -- might be better. Stay tuned.</p><h1><a id="rfc.status" href="#rfc.status">Status of this Memo</a></h1><p>This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.</p><p>Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at <a href="http://datatracker.ietf.org/drafts/current/">http://datatracker.ietf.org/drafts/current/</a>.</p><p>Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as &#8220;work in progress&#8221;.</p><p>This Internet-Draft will expire on January 4, 2013.</p><h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1><p>Copyright © 2012 IETF Trust and the persons identified as the document authors. All rights reserved.</p><p>This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.</p><hr class="noprint"><h1 class="np" id="rfc.toc"><a href="#rfc.toc">Table of Contents</a></h1><ul class="toc"><li>1.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.1">Introduction</a></li><li>2.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.2">Requirements</a></li><li>3.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.3">The Problem Details JSON Object</a></li><li>4.&nbsp;&nbsp;&nbsp;<a href="#the-problem-http-response-header-field">Expressing Problems with Link Headers</a></li><li>5.&nbsp;&nbsp;&nbsp;<a href="#defining">Defining New Problem Details</a></li><li>6.&nbsp;&nbsp;&nbsp;<a href="#generating-problems">Generating Problem Details</a></li><li>7.&nbsp;&nbsp;&nbsp;<a href="#consuming-problems">Consuming Problem Details</a></li><li>8.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.8">Security Considerations</a></li><li>9.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.9">IANA Considerations</a></li><li>10.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.10">Acknowledgements</a></li><li>11.&nbsp;&nbsp;&nbsp;<a href="#rfc.references">Normative References</a></li><li><a href="#rfc.authors">Author's Address</a></li></ul><h1 id="rfc.section.1" class="np"><a href="#rfc.section.1">1.</a>&nbsp;Introduction</h1><p id="rfc.section.1.p.1">While HTTP <a href="#RFC2616"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2616]</cite></a> defines the status code as the primary indicator of response semantics, it is sometimes not fine-grained enough to convey helpful information about the error, particularly to non-human consumers.</p><p id="rfc.section.1.p.2">For example, consider a 403 Forbidden response that indicates that the client's account doesn't have enough credit. While this can be adequately expressed in HTML if it's presented to a human in front of a Web browser, a non-browser client will have difficulty understanding the response, because it doesn't understand the structure of the markup.</p><p id="rfc.section.1.p.3">This specification proposes a "Problem Detail" as an extensible way to carry machine-readable details of errors in a response, to avoid the need to invent new response formats.</p><p id="rfc.section.1.p.4">Problem details have: </p><ul><li>A generic status, identified and solely conveyed by the HTTP status code &lt;<a href="http://www.iana.org/assignments/http-status-codes/">http://www.iana.org/assignments/http-status-codes/</a>&gt;. For example, "403 Forbidden".</li><li>An problem type that refines the status code semantics, identified by an absolute URI <a href="#RFC3986"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a> and paired with a summary title.</li><li>Optionally, detail that is specific to an instance of the problem.</li></ul><p id="rfc.section.1.p.5">This specification defines a common data model for problem details as a JSON <a href="#RFC4627"><cite title="The application/json Media Type for JavaScript Object Notation (JSON)">[RFC4627]</cite></a> object. That object can be serialised as an "application/json-problem" HTTP response, or it can be conveyed using a Link HTTP response header field <a href="#RFC5988"><cite title="Web Linking">[RFC5988]</cite></a>.</p><p id="rfc.section.1.p.6">Future work may include defining a HTML Microformat &lt;<a href="http://microformats.org/">http://microformats.org/</a>&gt; that allows this information to be carried in an HTML document as well.</p><h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a>&nbsp;Requirements</h1><p id="rfc.section.2.p.1">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <a href="#RFC2119"><cite title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</cite></a>.</p><h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a>&nbsp;The Problem Details JSON Object</h1><p id="rfc.section.3.p.1">The canonical format for problem details is a JSON <a href="#RFC4627"><cite title="The application/json Media Type for JavaScript Object Notation (JSON)">[RFC4627]</cite></a> document, identified with the "application/json-problem" media type. Its root object has the following properties:</p><ul><li>"describedby" (string) - A URL that identifies the type of problem. When dereferenced, it SHOULD provide human-readable documentation (e.g., using HTML).</li><li>"title" (string) - A short, human-readable summary of the problem. It SHOULD NOT change from instance to instance of the problem, except for purposes of localisation.</li><li>"detail" (string) - Optionally, additional, human readable detail specific to this instance of the problem.</li></ul><p id="rfc.section.3.p.3">Problem details, when serialised as JSON objects, MUST include the "describedby" and "title" properties. The "detail" property is always OPTIONAL.</p><p id="rfc.section.3.p.4">Problem types MAY extend their instances with additional properties. For example:</p><div id="rfc.figure.u.1"></div><pre>
</style><link rel="Contents" href="#rfc.toc"><link rel="Author" href="#rfc.authors"><link rel="Copyright" href="#rfc.copyrightnotice"><link rel="Chapter" title="1 Introduction" href="#rfc.section.1"><link rel="Chapter" title="2 Requirements" href="#rfc.section.2"><link rel="Chapter" title="3 The Problem Details JSON Object" href="#rfc.section.3"><link rel="Chapter" title="4 Expressing Problems with Link Headers" href="#rfc.section.4"><link rel="Chapter" title="5 Defining New Problem Details" href="#rfc.section.5"><link rel="Chapter" title="6 Generating Problem Details" href="#rfc.section.6"><link rel="Chapter" title="7 Consuming Problem Details" href="#rfc.section.7"><link rel="Chapter" title="8 Security Considerations" href="#rfc.section.8"><link rel="Chapter" title="9 IANA Considerations" href="#rfc.section.9"><link rel="Chapter" title="10 Acknowledgements" href="#rfc.section.10"><link rel="Chapter" href="#rfc.section.11" title="11 Normative References"><meta name="generator" content="http://greenbytes.de/tech/webdav/rfc2629.xslt, Revision 1.576, 2012-05-02 14:26:45, XSLT vendor: SAXON 9.1.0.8 from Saxonica http://www.saxonica.com/"><meta name="keywords" content="status, HTTP, error, problem"><link rel="schema.dct" href="http://purl.org/dc/terms/"><meta name="dct.creator" content="Nottingham, M."><meta name="dct.identifier" content="urn:ietf:id:draft-nottingham-http-problem-00"><meta name="dct.issued" scheme="ISO8601" content="2012-07-03"><meta name="dct.abstract" content="This specification proposes a &#34;Problem Detail&#34; as an extensible way to carry machine-readable details of HTTP errors in a response, to avoid the need to invent new response formats for non-human consumers."><meta name="description" content="This specification proposes a &#34;Problem Detail&#34; as an extensible way to carry machine-readable details of HTTP errors in a response, to avoid the need to invent new response formats for non-human consumers."></head><body><table class="header"><tbody><tr><td class="left">Network Working Group</td><td class="right">M. Nottingham</td></tr><tr><td class="left">Internet-Draft</td><td class="right">Rackspace</td></tr><tr><td class="left">Intended status: Informational</td><td class="right">July 3, 2012</td></tr><tr><td class="left">Expires: January 4, 2013</td><td class="right"></td></tr></tbody></table><p class="title">Indicating Details of Problems to Machines in HTTP<br><span class="filename">draft-nottingham-http-problem-00</span></p><h1 id="rfc.abstract"><a href="#rfc.abstract">Abstract</a></h1><p>This specification proposes a "Problem Detail" as an extensible way to carry machine-readable details of HTTP errors in a response, to avoid the need to invent new response formats for non-human consumers.</p><h1 id="rfc.note.1"><a href="#rfc.note.1">Note to Readers</a></h1><p>This specification is tentative (as all Internet-Drafts are, but even more so). It's not yet clear whether defining this format will improve things enough to balance out the harm it may cause, and so it may disappear at any time. Using it before it becomes an RFC may subject you to ridicule; you have been warned.</p><p>What's the problem? In a nutshell, this sort of thing might encourage tighter coupling, making applications more brittle. On the other hand, lots of people are doing this already, so having a common way to do it -- with lots of caveats about how it can be misused -- might be better. Stay tuned.</p><h1><a id="rfc.status" href="#rfc.status">Status of this Memo</a></h1><p>This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.</p><p>Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at <a href="http://datatracker.ietf.org/drafts/current/">http://datatracker.ietf.org/drafts/current/</a>.</p><p>Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as &#8220;work in progress&#8221;.</p><p>This Internet-Draft will expire on January 4, 2013.</p><h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1><p>Copyright © 2012 IETF Trust and the persons identified as the document authors. All rights reserved.</p><p>This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.</p><hr class="noprint"><h1 class="np" id="rfc.toc"><a href="#rfc.toc">Table of Contents</a></h1><ul class="toc"><li>1.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.1">Introduction</a></li><li>2.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.2">Requirements</a></li><li>3.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.3">The Problem Details JSON Object</a></li><li>4.&nbsp;&nbsp;&nbsp;<a href="#the-problem-http-response-header-field">Expressing Problems with Link Headers</a></li><li>5.&nbsp;&nbsp;&nbsp;<a href="#defining">Defining New Problem Details</a></li><li>6.&nbsp;&nbsp;&nbsp;<a href="#generating-problems">Generating Problem Details</a></li><li>7.&nbsp;&nbsp;&nbsp;<a href="#consuming-problems">Consuming Problem Details</a></li><li>8.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.8">Security Considerations</a></li><li>9.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.9">IANA Considerations</a></li><li>10.&nbsp;&nbsp;&nbsp;<a href="#rfc.section.10">Acknowledgements</a></li><li>11.&nbsp;&nbsp;&nbsp;<a href="#rfc.references">Normative References</a></li><li><a href="#rfc.authors">Author's Address</a></li></ul><h1 id="rfc.section.1" class="np"><a href="#rfc.section.1">1.</a>&nbsp;Introduction</h1><p id="rfc.section.1.p.1">While HTTP <a href="#RFC2616"><cite title="Hypertext Transfer Protocol -- HTTP/1.1">[RFC2616]</cite></a> defines the status code as the primary indicator of response semantics, it is sometimes not fine-grained enough to convey helpful information about the error, particularly to non-human consumers.</p><p id="rfc.section.1.p.2">For example, consider a 403 Forbidden response that indicates that the client's account doesn't have enough credit. While this can be adequately expressed in HTML if it's presented to a human in front of a Web browser, a non-browser client will have difficulty understanding the response, because it doesn't understand the structure of the markup.</p><p id="rfc.section.1.p.3">This specification proposes a "Problem Detail" as an extensible way to carry machine-readable details of errors in a response, to avoid the need to invent new response formats.</p><p id="rfc.section.1.p.4">Problem details have: </p><ul><li>A generic status, identified and solely conveyed by the HTTP status code &lt;<a href="http://www.iana.org/assignments/http-status-codes/">http://www.iana.org/assignments/http-status-codes/</a>&gt;. For example, "403 Forbidden".</li><li>An problem type that refines the status code semantics, identified by an absolute URI <a href="#RFC3986"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a> and paired with a summary title.</li><li>Optionally, detail that is specific to an instance of the problem.</li></ul><p id="rfc.section.1.p.5">This specification defines a common data model for problem details as a JSON <a href="#RFC4627"><cite title="The application/json Media Type for JavaScript Object Notation (JSON)">[RFC4627]</cite></a> object. That object can be serialised as an "application/json-problem" HTTP response, or it can be conveyed using a Link HTTP response header field <a href="#RFC5988"><cite title="Web Linking">[RFC5988]</cite></a>.</p><p id="rfc.section.1.p.6">Future work may include defining a HTML Microformat &lt;<a href="http://microformats.org/">http://microformats.org/</a>&gt; that allows this information to be carried in an HTML document as well.</p><h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a>&nbsp;Requirements</h1><p id="rfc.section.2.p.1">The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <a href="#RFC2119"><cite title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</cite></a>.</p><h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a>&nbsp;The Problem Details JSON Object</h1><p id="rfc.section.3.p.1">The canonical format for problem details is a JSON <a href="#RFC4627"><cite title="The application/json Media Type for JavaScript Object Notation (JSON)">[RFC4627]</cite></a> document, identified with the "application/json-problem" media type. Its root object has the following properties:</p><ul><li>"describedby" (string) - A URL that identifies the type of problem. When dereferenced, it SHOULD provide human-readable documentation (e.g., using HTML).</li><li>"title" (string) - A short, human-readable summary of the problem. It SHOULD NOT change from instance to instance of the problem, except for purposes of localisation.</li><li>"detail" (string) - Optionally, additional, human readable detail specific to this instance of the problem.</li></ul><p id="rfc.section.3.p.3">Problem details, when serialised as JSON objects, MUST include the "describedby" and "title" properties. The "detail" property is always OPTIONAL.</p><p id="rfc.section.3.p.4">Problem types MAY extend their instances with additional properties. For example:</p><div id="rfc.figure.u.1"></div><pre>
HTTP/1.1 403 Forbidden
Content-Type: application/json-problem
Content-Language: en
Expand Down
Loading

0 comments on commit fed5020

Please sign in to comment.