Skip to content
This repository
Browse code

One more "details"

  • Loading branch information...
commit 7e2271b59215f6a0125caa09e9fe4668baa12dd4 1 parent fed5020
Mark Nottingham authored
4 http-problem/draft-nottingham-http-problem-00.html
@@ -298,7 +298,7 @@
298 298 content: normal;
299 299 }
300 300 }
301   -</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>
  301 +</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 Problem Details 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 Problem Details 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>
302 302 HTTP/1.1 403 Forbidden
303 303 Content-Type: application/json-problem
304 304 Content-Language: en
@@ -309,7 +309,7 @@
309 309 "detail": "Your current balance is 30, but that costs 50.",
310 310 "balance": 30,
311 311 "account": "http://api.example.com/account/12345"
312   - }</pre><p id="rfc.section.3.p.6">Here, the out-of-credit problem (identified by its URI) indicates the reason for the 403 in "title", gives instance-specific details in "detail", and adds two extensions; "balance" conveys the account's balance, and "account" gives a link where the account can be topped up.</p><p id="rfc.section.3.p.7">Note that "describedby" is case-sensitive in the JSON object, as are all other property names.</p><h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a>&nbsp;<a id="the-problem-http-response-header-field" href="#the-problem-http-response-header-field">Expressing Problems with Link Headers</a></h1><p id="rfc.section.4.p.1">Because resources often use formats other than JSON to convey human-readable problem details, it is also possible to serialise Problem Details for non-browser consumption alongside them using a Link response header field <a href="#RFC5988"><cite title="Web Linking">[RFC5988]</cite></a>. For example:</p><div id="rfc.figure.u.2"></div><pre>
  312 + }</pre><p id="rfc.section.3.p.6">Here, the out-of-credit problem (identified by its URI) indicates the reason for the 403 in "title", gives instance-specific details in "detail", and adds two extensions; "balance" conveys the account's balance, and "account" gives a link where the account can be topped up.</p><p id="rfc.section.3.p.7">Note that "describedby" is case-sensitive in the JSON object, as are all other property names.</p><h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a>&nbsp;<a id="the-problem-http-response-header-field" href="#the-problem-http-response-header-field">Expressing Problem Details with Link Headers</a></h1><p id="rfc.section.4.p.1">Because resources often use formats other than JSON to convey human-readable problem details, it is also possible to serialise Problem Details for non-browser consumption alongside them using a Link response header field <a href="#RFC5988"><cite title="Web Linking">[RFC5988]</cite></a>. For example:</p><div id="rfc.figure.u.2"></div><pre>
313 313 HTTP/1.1 403 Forbidden
314 314 Content-Type: text/html
315 315 Content-Language: en
4 http-problem/draft-nottingham-http-problem-00.txt
@@ -76,7 +76,7 @@ Table of Contents
76 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
77 77 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3
78 78 3. The Problem Details JSON Object . . . . . . . . . . . . . . . . 3
79   - 4. Expressing Problems with Link Headers . . . . . . . . . . . . . 4
  79 + 4. Expressing Problem Details with Link Headers . . . . . . . . . 4
80 80 5. Defining New Problem Details . . . . . . . . . . . . . . . . . 5
81 81 6. Generating Problem Details . . . . . . . . . . . . . . . . . . 7
82 82 7. Consuming Problem Details . . . . . . . . . . . . . . . . . . . 7
@@ -207,7 +207,7 @@ Internet-Draft Problem Details July 2012
207 207 all other property names.
208 208
209 209
210   -4. Expressing Problems with Link Headers
  210 +4. Expressing Problem Details with Link Headers
211 211
212 212 Because resources often use formats other than JSON to convey human-
213 213 readable problem details, it is also possible to serialise Problem
2  http-problem/draft-nottingham-http-problem-00.xml
@@ -166,7 +166,7 @@
166 166
167 167 </section>
168 168
169   - <section anchor="the-problem-http-response-header-field" title="Expressing Problems with Link Headers">
  169 + <section anchor="the-problem-http-response-header-field" title="Expressing Problem Details with Link Headers">
170 170
171 171 <t>Because resources often use formats other than JSON to convey
172 172 human-readable problem details, it is also possible to serialise Problem

0 comments on commit 7e2271b

Please sign in to comment.
Something went wrong with that request. Please try again.