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/