idnits 2.17.1
draft-nottingham-http-problem-00.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (July 4, 2012) is 4286 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159)
** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187)
** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288)
Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group M. Nottingham
3 Internet-Draft Rackspace
4 Intended status: Informational July 4, 2012
5 Expires: January 5, 2013
7 Indicating Details of Problems to Machines in HTTP
8 draft-nottingham-http-problem-00
10 Abstract
12 This specification proposes a "Problem Detail" as an extensible way
13 to carry machine-readable details of HTTP errors in a response, to
14 avoid the need to invent new response formats for non-human
15 consumers.
17 Note to Readers
19 This specification is tentative (as all Internet-Drafts are, but even
20 more so). It's not yet clear whether defining this format will
21 improve things enough to balance out the harm it may cause, and so it
22 may disappear at any time. Using it before it becomes an RFC may
23 subject you to ridicule; you have been warned.
25 What's the problem? In a nutshell, this sort of thing might
26 encourage tighter coupling, making applications more brittle. On the
27 other hand, lots of people are doing this already, so having a common
28 way to do it -- with lots of caveats about how it can be misused --
29 might be better. Stay tuned.
31 Status of this Memo
33 This Internet-Draft is submitted in full conformance with the
34 provisions of BCP 78 and BCP 79.
36 Internet-Drafts are working documents of the Internet Engineering
37 Task Force (IETF). Note that other groups may also distribute
38 working documents as Internet-Drafts. The list of current Internet-
39 Drafts is at http://datatracker.ietf.org/drafts/current/.
41 Internet-Drafts are draft documents valid for a maximum of six months
42 and may be updated, replaced, or obsoleted by other documents at any
43 time. It is inappropriate to use Internet-Drafts as reference
44 material or to cite them other than as "work in progress."
46 This Internet-Draft will expire on January 5, 2013.
48 Copyright Notice
49 Copyright (c) 2012 IETF Trust and the persons identified as the
50 document authors. All rights reserved.
52 This document is subject to BCP 78 and the IETF Trust's Legal
53 Provisions Relating to IETF Documents
54 (http://trustee.ietf.org/license-info) in effect on the date of
55 publication of this document. Please review these documents
56 carefully, as they describe your rights and restrictions with respect
57 to this document. Code Components extracted from this document must
58 include Simplified BSD License text as described in Section 4.e of
59 the Trust Legal Provisions and are provided without warranty as
60 described in the Simplified BSD License.
62 Table of Contents
64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
65 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3
66 3. The Problem Details JSON Object . . . . . . . . . . . . . . . . 4
67 4. Expressing Problem Details with Link Headers . . . . . . . . . 5
68 5. Defining New Problem Details . . . . . . . . . . . . . . . . . 5
69 6. Generating Problem Details . . . . . . . . . . . . . . . . . . 7
70 7. Consuming Problem Details . . . . . . . . . . . . . . . . . . . 7
71 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 8
72 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8
73 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9
74 11. Normative References . . . . . . . . . . . . . . . . . . . . . 9
75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9
77 1. Introduction
79 While HTTP [RFC2616] defines the status code as the primary indicator
80 of response semantics, it is sometimes not fine-grained enough to
81 convey helpful information about the error, particularly to non-human
82 consumers.
84 For example, consider a 403 Forbidden response that indicates that
85 the client's account doesn't have enough credit. While this can be
86 adequately expressed in HTML if it's presented to a human in front of
87 a Web browser, a non-browser client will have difficulty
88 understanding the response, because it doesn't understand the
89 structure of the markup.
91 This specification defines a "Problem Detail" as an extensible way to
92 carry machine-readable details of errors in a response, to avoid the
93 need to invent new response formats.
95 Problem details have:
96 o A generic status, identified and solely conveyed by the HTTP
97 status code .
98 For example, "403 Forbidden".
99 o An problem type that refines the status code semantics, identified
100 by an absolute URI [RFC3986] and paired with a summary title.
101 o Optionally, detail that is specific to an instance of the problem.
103 The common data model for problem details as a JSON [RFC4627] object.
104 That object can be serialised as an "application/json-problem" HTTP
105 response, or it can be conveyed using a Link HTTP response header
106 field [RFC5988].
108 Future work may include defining a HTML Microformat
109 that allows this information to be carried
110 in an HTML document as well.
112 Note that Problem Details are not the only way to convey the details
113 of a problem in HTTP; if the response is still a representation of a
114 resource, for example, it's often preferable to accommodate
115 describing the details in that format.
117 Rather, the aim of this specification is to define a common format
118 for those applications that need one, so that they aren't required to
119 define their own.
121 2. Requirements
123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
125 document are to be interpreted as described in [RFC2119].
127 3. The Problem Details JSON Object
129 The canonical format for problem details is a JSON [RFC4627]
130 document, identified with the "application/json-problem" media type.
131 Its root object has the following properties:
133 o "describedby" (string) - A URL that identifies the type of
134 problem. When dereferenced, it SHOULD provide human-readable
135 documentation (e.g., using HTML).
136 o "title" (string) - A short, human-readable summary of the problem.
137 It SHOULD NOT change from instance to instance of the problem,
138 except for purposes of localisation.
139 o "detail" (string) - Optionally, additional, human readable detail
140 specific to this instance of the problem.
142 Problem details, when serialised as JSON objects, MUST include the
143 "describedby" and "title" properties. The "detail" property is
144 always OPTIONAL.
146 Problem types MAY extend their instances with additional properties.
147 For example:
149 HTTP/1.1 403 Forbidden
150 Content-Type: application/json-problem
151 Content-Language: en
153 {
154 "describedby": "http://example.com/probs/out-of-credit",
155 "title": "You do not have enough credits.",
156 "detail": "Your current balance is 30, but that costs 50.",
157 "balance": 30,
158 "account": "http://api.example.com/account/12345"
159 }
161 Here, the out-of-credit problem (identified by its URI) indicates the
162 reason for the 403 in "title", gives instance-specific details in
163 "detail", and adds two extensions; "balance" conveys the account's
164 balance, and "account" gives a link where the account can be topped
165 up.
167 Note that "describedby" is case-sensitive in the JSON object, as are
168 all other property names.
170 4. Expressing Problem Details with Link Headers
172 Because resources often use formats other than JSON to convey human-
173 readable problem details, it is also possible to serialise Problem
174 Details for non-browser consumption alongside them using a Link
175 response header field [RFC5988]. For example:
177 HTTP/1.1 403 Forbidden
178 Content-Type: text/html
179 Content-Language: en
180 Link: ; rel="describedby";
181 title="You do not have enough credits."; balance=30;
182 account="http://api.example.com/account/12345"
184 Here, the same problem as above is conveyed using the header in
185 previous examples, but without the optional detail.
187 Problem details are serialised into Link headers using the
188 "describedby" link relation type, with the URL for the problem type
189 as the link target. The title is conveyed using the "title"
190 parameter, and the detail can be conveyed using the "detail"
191 parameter.
193 Extension parameters on the JSON Object can also be expressed as
194 target parameters on the link header, as long as the extension either
195 defines them as a string, or explains how to express them as one.
197 The title, detail, and extension properties MUST use the encoding
198 specified in [RFC5987] if it falls outside of the US-ASCII character
199 set.
201 For example, the following are all valid:
203 Link: ; rel="describedby"; title="Hi"
204 Link: ; rel="describedby"; title="Hi"
205 Link: ; rel="describedby";
206 title="Hi there"; detail="something happened."
207 Link: ; rel="describedby"; other="foo";
208 title="Hi there"; title*=UTF-8''Hi%20there; another=bar;
209 detail*=UTF-8''something%20happened
211 5. Defining New Problem Details
213 Before defining a new type of problem detail, it's important to
214 understand what they are good for, and what's better left to other
215 mechanisms.
217 Problem details are not a debugging tool for the underlying
218 implementation; rather, they are a way to expose greater detail about
219 the HTTP interface of the application itself.
221 For example, an "out of credit" problem is an appropriate explanation
222 as to why a request was forbidden. In contrast, a description of the
223 internal conditions that led to a 500 Internal Server Error along
224 with a stack trace are not an appropriate use of this mechanism,
225 because it exposes implementation detail, rather than explaining the
226 interface.
228 At the other end of the spectrum, truly generic problems - i.e.,
229 conditions that could potentially apply to any resource on the Web -
230 are usually better expressed as plain status codes.
232 For example, a "write access disallowed" problem is unnecessary,
233 since a 403 Forbidden status code on a PUT request is self-
234 explanatory.
236 Finally, a problem domain may have a more appropriate way to carry an
237 error in a format that it already defines. Problem details are
238 intended to avoid the necessity of establishing new "fault" or
239 "error" document formats, not to replace existing domain-specific
240 formats. That said, it is possible to add support for problems using
241 HTTP server-driven content negotiation (i.e., the client uses the
242 Accept request header to indicate a preference for problems).
244 If defining a new problem still seems wise, one can be created by:
245 1. Nominating a describedby URL (typically, with the "http" scheme),
246 2. Choosing a title that appropriately describes it (think short),
247 and
248 3. Nominating a HTTP status code for it to be used with.
250 Problem types MAY specify the use of the Retry-After response header
251 in appropriate circumstances.
253 A problem's describedby URL SHOULD resolve to HTML documentation that
254 explains how to resolve the problem.
256 Optionally, a problem definition MAY specify additional properties on
257 the Problem Details JSON object.
259 For example, an extension might use typed links [RFC5988] to another
260 resource that can be used by machines to resolve the problem.
262 If an extension is defined, its name SHOULD conform to token
263 [RFC2616], so that it can be serialised in header and other formats.
265 Likewise, problems defining extensions should either make their
266 values strings, or explain how to map their values to strings that
267 are safe to include in HTTP headers (noting the special semantics of
268 a comma there).
270 6. Generating Problem Details
272 The URL used in the describedby property MUST NOT be changed in any
273 way from that defined by its specification; doing so turns it into a
274 different problem that most consumers will not recognise.
276 The title string SHOULD be sent as specified by the problem
277 definition, although it MAY be localised (e.g., using server-driven
278 content negotiation, with the "Accept-Language" request header).
279 Remember that such responses are required by HTTP to include a Vary
280 header, e.g.:
282 HTTP/1.1 403 Forbidden
283 Content-Type: text/html
284 Content-Language: se
285 Vary: Accept-Language
286 Link: ;
287 rel="describedby";
288 title*=UTF-8''Du%20%C3%A4r%20ute%20p%C3%A5%20pengar.
290 Note the use of RFC5987 encoding here. Problem details SHOULD be
291 served with Content-Language headers, even if negotiation isn't used,
292 to aid in localisation.
294 The information conveyed in the detail property, if present, SHOULD
295 focus on helping the client correct the problem, rather than giving
296 debugging information.
298 Software that generates problems should note that only one problem
299 can be sent at at time.
301 7. Consuming Problem Details
303 Consumers should use the describedby URL as the primary identifier
304 for the problem; the title string is advisory, and included only for
305 users who are not aware of the semantics of the URL, and don't have
306 the ability to discover them (e.g., offline log analysis).
308 Likewise, the detail property SHOULD NOT be parsed for information by
309 clients; extensions are more suitable and less error-prone ways to
310 obtain such information.
312 Clients consuming problem details MUST ignore unrecognised
313 extensions; this allows problems to evolve and include additional
314 information in the future.
316 Finally, clients consuming problem details SHOULD NOT automatically
317 deference the describedby URL; it is not intended for machine
318 interaction.
320 8. Security Considerations
322 When defining a new problem, the information included must be
323 carefully vetted. Likewise, when actually generating a problem -
324 however it is serialised - the details given must also be
325 scrutinised.
327 Risks include leaking information that can be exploited to compromise
328 the system, access to the system, or the privacy of users of the
329 system.
331 9. IANA Considerations
333 This specification defines a new Internet media type, "application/
334 json-problem":
336 Type name: application
337 Subtype name: json-problem
338 Required parameters: None
339 Optional parameters: None; unrecognised parameters
340 should be ignored
341 Encoding considerations: Same as [RFC4627]
342 Security considerations: see [this document]
343 Interoperability considerations: None.
344 Published specification: [this document]
345 Applications that use this media type: HTTP
346 Additional information:
347 Magic number(s): n/a
348 File extension(s): n/a
349 Macintosh file type code(s): n/a
350 Person & email address to contact for further information:
351 Mark Nottingham
352 Intended usage: COMMON
353 Restrictions on usage: None.
354 Author: Mark Nottingham
355 Change controller: IESG
357 10. Acknowledgements
359 The author would like to thank Jan Algermissen, Mike Amundsen, Subbu
360 Allamaraju, Roy Fielding, Sam Johnston, Julian Reschke, James Snell,
361 and Erik Wilde for early review of this specification (even if some
362 disagree with parts of it).
364 11. Normative References
366 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
367 Requirement Levels", BCP 14, RFC 2119, March 1997.
369 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
370 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
371 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
373 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
374 Resource Identifier (URI): Generic Syntax", STD 66,
375 RFC 3986, January 2005.
377 [RFC4627] Crockford, D., "The application/json Media Type for
378 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
380 [RFC5987] Reschke, J., "Character Set and Language Encoding for
381 Hypertext Transfer Protocol (HTTP) Header Field
382 Parameters", RFC 5987, August 2010.
384 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
386 Author's Address
388 Mark Nottingham
389 Rackspace
391 Email: mnot@mnot.net
392 URI: http://www.mnot.net/