idnits 2.17.1 draft-nottingham-http-problem-01.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 13, 2012) is 4214 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: 5 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 September 13, 2012 4 Intended status: Informational 5 Expires: March 17, 2013 7 Indicating Details of Problems to Machines in HTTP 8 draft-nottingham-http-problem-01 10 Abstract 12 This document defines a "Problem Detail" as an extensible way to 13 carry machine-readable details of HTTP errors in a response, to avoid 14 the need to invent new response formats for non-human consumers. 16 Note to Readers 18 This draft should be discussed on the apps-discuss mailing list [1]. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on March 17, 2013. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. The Problem Details JSON Object . . . . . . . . . . . . . . . . 3 57 4. Expressing Problem Details with Link Headers . . . . . . . . . 4 58 5. Defining New Problem Details . . . . . . . . . . . . . . . . . 5 59 6. Generating Problem Details . . . . . . . . . . . . . . . . . . 7 60 7. Consuming Problem Details . . . . . . . . . . . . . . . . . . . 7 61 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 62 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 63 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 64 11. Normative References . . . . . . . . . . . . . . . . . . . . . 9 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 1. Introduction 69 While HTTP [RFC2616] defines the status code as the primary indicator 70 of generic response semantics, it is sometimes not fine-grained 71 enough to convey helpful information about the error, particularly to 72 non-human consumers. 74 For example, consider a 403 Forbidden response that indicates that 75 the client's account doesn't have enough credit. While this can be 76 adequately expressed in HTML if it's presented to a human in front of 77 a Web browser, a non-browser client will have difficulty 78 understanding the response, because it doesn't understand the 79 structure of the markup. 81 This specification defines a "Problem Detail" as an extensible way to 82 carry machine-readable details of errors in a response, to avoid the 83 need to invent new, application-specific response formats. 85 The common data model for problem details as a JSON [RFC4627] object. 86 That object can be serialised as an "application/json-problem" HTTP 87 response, or it can be conveyed using a Link HTTP response header 88 field [RFC5988]. 90 Note that this format is (naturally) not the only way to convey the 91 details of a problem in HTTP; if the response is still a 92 representation of a resource, for example, it's often preferable to 93 accommodate describing the details in that format. 95 As such, the aim of this specification is to define a common format 96 for those applications that need one, so that they aren't required to 97 define their own. 99 2. Requirements 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in [RFC2119]. 105 3. The Problem Details JSON Object 107 The canonical format for problem details is a JSON [RFC4627] 108 document, identified with the "application/json-problem" media type. 109 Its root object has the following properties: 111 o "describedby" (string) - An absolute URI [RFC3986] that identifies 112 the type of problem. When dereferenced, it SHOULD provide human- 113 readable documentation (e.g., using HTML). 114 o "title" (string) - A short, human-readable summary of the problem. 115 It SHOULD NOT change from instance to instance of the problem, 116 except for purposes of localisation. 117 o "instance" (string) - An absolute URI that identifies the specific 118 instance of the problem. It may or may not yield further 119 information if dereferenced. 120 o "detail" (string) - Optionally, an additional, human readable 121 explanation specific to this instance of the problem. 123 Problem details, when serialised as JSON objects, MUST include the 124 "describedby" and "title" properties. The "instance" and "detail" 125 properties are always OPTIONAL. 127 Problem types MAY extend their instances with additional properties. 128 For example: 130 HTTP/1.1 403 Forbidden 131 Content-Type: application/json-problem 132 Content-Language: en 134 { 135 "describedby": "http://example.com/probs/out-of-credit", 136 "title": "You do not have enough credits.", 137 "detail": "Your current balance is 30, but that costs 50.", 138 "instance": "http://server.example.net/problems/12345abc", 139 "balance": 30, 140 "account": "http://api.example.com/account/12345" 141 } 143 Here, the out-of-credit problem (identified by its URI) indicates the 144 reason for the 403 in "title", gives a reference for the specific 145 problem occurrence with "instance" and gives instance-specific 146 details in "detail", and adds two extensions; "balance" conveys the 147 account's balance, and "account" gives a link where the account can 148 be topped up. 150 Note that "describedby" is case-sensitive in the JSON object, as are 151 all other property names. 153 4. Expressing Problem Details with Link Headers 155 Because resources often use formats other than JSON to convey human- 156 readable problem details, it is also possible to serialise Problem 157 Details for non-browser consumption alongside them using a Link 158 response header field [RFC5988]. For example: 160 HTTP/1.1 403 Forbidden 161 Content-Type: text/html 162 Content-Language: en 163 Link: ; rel="describedby"; 164 instance="http://server.example.net/problems/12345abc"; 165 title="You do not have enough credits."; balance=30; 166 account="http://api.example.com/account/12345" 168 Here, the same problem as above is conveyed using the header in 169 previous examples, but without the optional detail. 171 Problem details are serialised into Link headers using the 172 "describedby" link relation type, with the URL for the problem type 173 as the link target. The title is conveyed using the "title" 174 parameter, and the detail can be conveyed using the "detail" 175 parameter. 177 Extension parameters on the JSON Object can also be expressed as 178 target parameters on the link header, as long as the extension either 179 defines them as a string, or explains how to express them as one. 181 The title, detail, and extension properties MUST use the encoding 182 specified in [RFC5987] if it falls outside of the US-ASCII character 183 set. 185 For example, the following are all valid: 187 Link: ; rel="describedby"; title="Hi" 188 Link: ; rel="describedby"; title="Hi" 189 Link: ; rel="describedby"; 190 title="Hi there"; detail="something happened." 191 Link: ; rel="describedby"; other="foo"; 192 title="Hi there"; title*=UTF-8''Hi%20there; another=bar; 193 detail*=UTF-8''something%20happened 195 5. Defining New Problem Details 197 Before defining a new type of problem detail, it's important to 198 understand what they are good for, and what's better left to other 199 mechanisms. 201 Problem details are not a debugging tool for the underlying 202 implementation; rather, they are a way to expose greater detail about 203 the HTTP interface of the application itself. 205 For example, an "out of credit" problem is an appropriate explanation 206 as to why a request was forbidden. In contrast, a description of the 207 internal conditions that led to a 500 Internal Server Error along 208 with a stack trace are not an appropriate use of this mechanism, 209 because it exposes implementation detail, rather than explaining the 210 interface. 212 At the other end of the spectrum, truly generic problems - i.e., 213 conditions that could potentially apply to any resource on the Web - 214 are usually better expressed as plain status codes. 216 For example, a "write access disallowed" problem is unnecessary, 217 since a 403 Forbidden status code on a PUT request is self- 218 explanatory. 220 Finally, a problem domain may have a more appropriate way to carry an 221 error in a format that it already defines. Problem details are 222 intended to avoid the necessity of establishing new "fault" or 223 "error" document formats, not to replace existing domain-specific 224 formats. That said, it is possible to add support for problems using 225 HTTP server-driven content negotiation (i.e., the client uses the 226 Accept request header to indicate a preference for problems). 228 If defining a new problem still seems wise, one can be created by: 229 1. Nominating a describedby URL (typically, with the "http" scheme), 230 2. Choosing a title that appropriately describes it (think short), 231 and 232 3. Nominating a HTTP status code for it to be used with. 234 Problem types MAY specify the use of the Retry-After response header 235 in appropriate circumstances. 237 A problem's describedby URL SHOULD resolve to HTML documentation that 238 explains how to resolve the problem. 240 Optionally, a problem definition MAY specify additional properties on 241 the Problem Details JSON object. 243 For example, an extension might use typed links [RFC5988] to another 244 resource that can be used by machines to resolve the problem. 246 If an extension is defined, its name SHOULD conform to token 247 [RFC2616], so that it can be serialised in header and other formats. 249 Likewise, problems defining extensions should either make their 250 values strings, or explain how to map their values to strings that 251 are safe to include in HTTP headers (noting the special semantics of 252 a comma there). 254 6. Generating Problem Details 256 The URL used in the describedby property MUST NOT be changed in any 257 way from that defined by its specification; doing so turns it into a 258 different problem that most consumers will not recognise. 260 The title string SHOULD be sent as specified by the problem 261 definition, although it MAY be localised (e.g., using server-driven 262 content negotiation, with the "Accept-Language" request header). 263 Remember that such responses are required by HTTP to include a Vary 264 header, e.g.: 266 HTTP/1.1 403 Forbidden 267 Content-Type: text/html 268 Content-Language: se 269 Vary: Accept-Language 270 Link: ; 271 rel="describedby"; 272 title*=UTF-8''Du%20%C3%A4r%20ute%20p%C3%A5%20pengar. 274 Note the use of RFC5987 encoding here. Problem details SHOULD be 275 served with Content-Language headers, even if negotiation isn't used, 276 to aid in localisation. 278 The information conveyed in the detail property, if present, SHOULD 279 focus on helping the client correct the problem, rather than giving 280 debugging information. 282 The instance property, if present, MUST be globally unique to that 283 particular occurrence of the problem. 285 Software that generates problems should note that only one problem 286 can be sent at at time. 288 7. Consuming Problem Details 290 Consumers should use the describedby URL as the primary identifier 291 for the problem; the title string is advisory, and included only for 292 users who are not aware of the semantics of the URL, and don't have 293 the ability to discover them (e.g., offline log analysis). 295 Likewise, the detail property SHOULD NOT be parsed for information by 296 clients; extensions are more suitable and less error-prone ways to 297 obtain such information. 299 Clients consuming problem details MUST ignore unrecognised 300 extensions; this allows problems to evolve and include additional 301 information in the future. 303 Finally, clients consuming problem details SHOULD NOT automatically 304 deference the describedby URL; it is not intended for machine 305 interaction. 307 8. Security Considerations 309 When defining a new problem, the information included must be 310 carefully vetted. Likewise, when actually generating a problem - 311 however it is serialised - the details given must also be 312 scrutinised. 314 Risks include leaking information that can be exploited to compromise 315 the system, access to the system, or the privacy of users of the 316 system. 318 9. IANA Considerations 320 This specification defines a new Internet media type, "application/ 321 json-problem": 323 Type name: application 324 Subtype name: json-problem 325 Required parameters: None 326 Optional parameters: None; unrecognised parameters 327 should be ignored 328 Encoding considerations: Same as [RFC4627] 329 Security considerations: see [this document] 330 Interoperability considerations: None. 331 Published specification: [this document] 332 Applications that use this media type: HTTP 333 Additional information: 334 Magic number(s): n/a 335 File extension(s): n/a 336 Macintosh file type code(s): n/a 337 Person & email address to contact for further information: 338 Mark Nottingham 339 Intended usage: COMMON 340 Restrictions on usage: None. 341 Author: Mark Nottingham 342 Change controller: IESG 344 10. Acknowledgements 346 The author would like to thank Jan Algermissen, Mike Amundsen, Subbu 347 Allamaraju, Roy Fielding, Sam Johnston, Julian Reschke, James Snell, 348 and Erik Wilde for early review of this specification (even if some 349 disagree with parts of it). 351 11. Normative References 353 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 354 Requirement Levels", BCP 14, RFC 2119, March 1997. 356 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 357 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 358 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 360 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 361 Resource Identifier (URI): Generic Syntax", STD 66, 362 RFC 3986, January 2005. 364 [RFC4627] Crockford, D., "The application/json Media Type for 365 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 367 [RFC5987] Reschke, J., "Character Set and Language Encoding for 368 Hypertext Transfer Protocol (HTTP) Header Field 369 Parameters", RFC 5987, August 2010. 371 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 373 [1] 375 Author's Address 377 Mark Nottingham 379 Email: mnot@mnot.net 380 URI: http://www.mnot.net/