idnits 2.17.1 draft-nottingham-http-problem-05.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 == Line 507 has weird spacing: '...element type ...' == Line 508 has weird spacing: '...element title...' == Line 509 has weird spacing: '...element detai...' == Line 510 has weird spacing: '...element statu...' == Line 511 has weird spacing: '...element insta...' == (1 more instance...) -- The document date (December 9, 2013) is 3784 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 informational reference (is this intentional?): RFC 3023 (Obsoleted by RFC 7303) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft Akamai 4 Intended status: Informational E. Wilde 5 Expires: June 12, 2014 EMC 6 December 9, 2013 8 Problem Details for HTTP APIs 9 draft-nottingham-http-problem-05 11 Abstract 13 This document defines a "problem detail" as a way to carry machine- 14 readable details of errors in a HTTP response, to avoid the need to 15 invent new error response formats for HTTP APIs. 17 Note to Readers 19 This draft should be discussed on the apps-discuss mailing list [1]. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on June 12, 2014. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4 58 3.1. Required Members . . . . . . . . . . . . . . . . . . . . . 5 59 3.2. Optional Members . . . . . . . . . . . . . . . . . . . . . 5 60 3.3. Extension Members . . . . . . . . . . . . . . . . . . . . 6 61 4. Defining New Problem Types . . . . . . . . . . . . . . . . . . 6 62 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 7 64 5. Using Problem Details with Other Formats . . . . . . . . . . . 8 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 68 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 9.1. Normative References . . . . . . . . . . . . . . . . . . . 10 70 9.2. Informative References . . . . . . . . . . . . . . . . . . 11 71 Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . . 12 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 74 1. Introduction 76 HTTP [RFC2616] status codes are sometimes not sufficient to convey 77 enough information about an error to be helpful. While humans behind 78 Web browsers can be informed about the nature of the problem with an 79 HTML [W3C.REC-html401-19991224] response body, non-human consumers of 80 so-called "HTTP APIs" are usually not. 82 This specification defines simple JSON [RFC4627] and XML 83 [W3C.REC-xml-20081126] document formats to suit this purpose. They 84 are designed to be reused by HTTP APIs, which can identify distinct 85 "problem types" specific to their needs. 87 Thus, API clients can be informed of both the high-level error class 88 (using the status code) and the finer-grained details of the problem 89 (using one of these formats). 91 For example, consider a response that indicates that the client's 92 account doesn't have enough credit. The 403 Forbidden status code 93 might be deemed most appropriate to use, as it will inform HTTP- 94 generic software (such as client libraries, caches and proxies) of 95 the general semantics of the response. 97 However, that doesn't give the API client enough information about 98 why the request was forbidden, the applicable account balance, or how 99 to correct the problem. If these details are included in the 100 response body in a machine-readable format, the client can treat it 101 appropriately; for example, triggering a transfer of more credit into 102 the account. 104 This specification does this by identifying a specific type of 105 problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can 106 do this by nominating new URIs under their control, or by reusing 107 existing ones. 109 Additionally, problems can contain other information, such as a URI 110 that identifies the specific occurrence of the problem (effectively 111 giving an identifier to the concept "The time Joe didn't have enough 112 credit last Thursday"), which may be useful for support or forensic 113 purposes. 115 The data model for problem details is a JSON [RFC4627] object; when 116 formatted as a JSON document, it uses the "application/problem+json" 117 media type. Appendix A defines how to express them in an equivalent 118 XML format, which uses the "application/problem+xml" media type. 120 Note that problem details are (naturally) not the only way to convey 121 the details of a problem in HTTP; if the response is still a 122 representation of a resource, for example, it's often preferable to 123 accommodate describing the relevant details in that application's 124 format. Likewise, in many situations, there is an appropriate HTTP 125 status code that does not require extra detail to be conveyed. 127 Instead, the aim of this specification is to define common error 128 formats for those applications that need one, so that they aren't 129 required to define their own, or worse, tempted to re-define the 130 semantics of existing HTTP status codes. 132 2. Requirements 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in [RFC2119]. 138 3. The Problem Details JSON Object 140 The canonical model for problem details is a JSON [RFC4627] object. 142 When serialised as a JSON document, that format is identified with 143 the "application/problem+json" media type. 145 For example, a HTTP response carrying JSON problem details: 147 HTTP/1.1 403 Forbidden 148 Content-Type: application/problem+json 149 Content-Language: en 151 { 152 "type": "http://example.com/probs/out-of-credit", 153 "title": "You do not have enough credit.", 154 "detail": "Your current balance is 30, but that costs 50.", 155 "instance": "http://example.net/account/12345/msgs/abc", 156 "balance": 30, 157 "accounts": ["http://example.net/account/12345", 158 "http://example.net/account/67890"] 159 } 161 Here, the out-of-credit problem (identified by its type URI) 162 indicates the reason for the 403 in "title", gives a reference for 163 the specific problem occurrence with "instance", gives occurrence- 164 specific details in "detail", and adds two extensions; "balance" 165 conveys the account's balance, and "accounts" gives a link where the 166 account can be topped up. 168 Note that "type" is case-sensitive in the JSON object, as are all 169 other member names. 171 3.1. Required Members 173 A problem details object MUST have the following members: 175 o "type" (string) - An absolute URI [RFC3986] that identifies the 176 problem type. When dereferenced, it SHOULD provide human-readable 177 documentation for the problem type (e.g., using HTML 178 [W3C.REC-html401-19991224]). 179 o "title" (string) - A short, human-readable summary of the problem 180 type. It SHOULD NOT change from occurrence to occurrence of the 181 problem, except for purposes of localisation. 183 Consumers MUST use the type string as the primary identifier for the 184 problem type; the title string is advisory, and included only for 185 users who are not aware of the semantics of the URI, and don't have 186 the ability to discover them (e.g., offline log analysis). Consumers 187 SHOULD NOT automatically dereference the type URI. 189 3.2. Optional Members 191 Furthermore, a problem details object MAY have the following members: 193 o "status" (number) - The HTTP status code ([RFC2616], Section 6) 194 generated by the origin server for this occurrence of the problem. 195 o "detail" (string) - An human readable explanation specific to this 196 occurrence of the problem. 197 o "instance" (string) - An absolute URI that identifies the specific 198 occurrence of the problem. It may or may not yield further 199 information if dereferenced. 201 The status member, if present, is only advisory; it conveys the HTTP 202 status code used for the convenience of the consumer. Generators 203 MUST use the same status code in the actual HTTP response, to assure 204 that generic HTTP software that does not understand this format still 205 behaves correctly. See Section 6 for further caveats regarding its 206 use. 208 The detail member, if present, SHOULD focus on helping the client 209 correct the problem, rather than giving debugging information. 211 Consumers SHOULD NOT parse the detail member for information; 212 extensions are more suitable and less error-prone ways to obtain such 213 information. 215 3.3. Extension Members 217 Finally, problem type definitions MAY extend the problem details 218 object with additional members. 220 Clients consuming problem details MUST ignore any such extensions 221 that they don't recognise; this allows problem types to evolve and 222 include additional information in the future. 224 4. Defining New Problem Types 226 When an HTTP API needs to define a response that indicates an error 227 condition, it might be appropriate to do so by defining a new problem 228 type. 230 Before doing so, it's important to understand what they are good for, 231 and what's better left to other mechanisms. 233 Problem details are not a debugging tool for the underlying 234 implementation; rather, they are a way to expose greater detail about 235 the HTTP interface itself. New problem types need to carefully 236 consider the Security Considerations (Section 6); in particular the 237 risk of exposing attack vectors by exposing implementation internals 238 through error messages. 240 Likewise, truly generic problems - i.e., conditions that could 241 potentially apply to any resource on the Web - are usually better 242 expressed as plain status codes. For example, a "write access 243 disallowed" problem is probably unnecessary, since a 403 Forbidden 244 status code on a PUT request is self-explanatory. 246 Finally, an application may have a more appropriate way to carry an 247 error in a format that it already defines. Problem details are 248 intended to avoid the necessity of establishing new "fault" or 249 "error" document formats, not to replace existing domain-specific 250 formats. 252 That said, it is possible to add support for problem details to 253 existing HTTP APIs using HTTP content negotiation (e.g., using the 254 Accept request header to indicate a preference for this format). 256 New problem type definitions MUST document: 257 1. A type URI (typically, with the "http" scheme), 258 2. A title that appropriately describes it (think short), and 259 3. The HTTP status code for it to be used with. 261 Problem types MAY specify the use of the Retry-After response header 262 in appropriate circumstances. 264 A problem's type URI SHOULD resolve to HTML 265 [W3C.REC-html401-19991224] documentation that explains how to resolve 266 the problem. 268 A problem type definition MAY specify additional members on the 269 Problem Details object. For example, an extension might use typed 270 links [RFC5988] to another resource that can be used by machines to 271 resolve the problem. 273 If such additional members are defined, their names SHOULD start with 274 a letter (ALPHA, as per [RFC5234]) and SHOULD consist of characters 275 from ALPHA, DIGIT, and "_" (so that it can be serialized in formats 276 other than JSON), and SHOULD be three characters or longer. 278 4.1. Example 280 For example, if you are publishing an HTTP API to your online 281 shopping cart, you might need to indicate that the user is out of 282 credit (our example from above), and therefore cannot make the 283 purchase. 285 If you already have an application-specific format that can 286 accommodate this information, it's probably best to do that. 287 However, if you don't, you might consider using one of the problem 288 details formats; JSON if your API is JSON-based, or XML if it uses 289 that convention. 291 To do so, you might look for an already-defined type URI that suits 292 your purposes. If one is available, you can reuse that URI. 294 If one isn't available, you could mint and document a new type URI 295 (which ought to be under your control and stable over time), an 296 appropriate title and the HTTP status code that it will be used with, 297 along with what it means and how it should be handled. 299 In summary: an instance URI will always identify a specific 300 occurrence of a problem. On the other hand, type URIs can be reused 301 if an appropriate description of a problem type is already available 302 someplace else, or they can be created for new problem types. 304 4.2. Pre-Defined Problem Types 306 This specification reserves the use of one URI as a problem type. 308 The "about:blank" URI [RFC6694], when used as a problem type, 309 indicates that the problem has no additional semantics beyond that of 310 the HTTP status code. 312 When "about:blank" is used, the title SHOULD be the same as the 313 recommended HTTP status phrase for that code (e.g., "Not Found" for 314 404, and so on), although it MAY be localized to suit client 315 preferences (expressed with the Accept-Language request header). 317 5. Using Problem Details with Other Formats 319 In some situations, it can be advantageous to embed Problem Details 320 in formats other than those described here. For example, an API that 321 uses HTML [W3C.REC-html401-19991224] might want to also use HTML for 322 expressing its problem details. 324 Problem details can be embedded in other formats by either 325 encapsulating one of the existing serializations (JSON or XML) into 326 that format, or by translating the model of a Problem Detail (as 327 specified in Section 3) into the format's conventions. 329 For example, in HTML, a problem could be embedded by encapsulating 330 JSON in a script tag: 332 343 } 345 or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20120607]. 347 This specification does not make specific recommendations regarding 348 embedding Problem Details in other formats; the appropriate way to 349 embed them depends both upon the format in use and application of 350 that format. 352 6. Security Considerations 354 When defining a new problem type, the information included must be 355 carefully vetted. Likewise, when actually generating a problem - 356 however it is serialized - the details given must also be 357 scrutinized. 359 Risks include leaking information that can be exploited to compromise 360 the system, access to the system, or the privacy of users of the 361 system. 363 Generators providing links to occurrence information are encouraged 364 to avoid making implementation details such as a stack dump available 365 through the HTTP interface, since this can expose sensitive details 366 of the server implementation, its data, and so on. 368 The "status" member duplicates the information available in the HTTP 369 status code itself, thereby bringing the possibility of disagreement 370 between the two. Their relative precedence is not clear, since a 371 disagreement might indicate that (for example) an intermediary has 372 modified the HTTP status code in transit. As such, those defining 373 problem types as well as generators and consumers of problems need to 374 be aware that generic software (such as proxies, load balancers, 375 firewalls, virus scanners) are unlikely to know of or respect the 376 status code conveyed in this member. 378 7. IANA Considerations 380 This specification defines two new Internet media types [RFC6838]: 382 Type name: application 383 Subtype name: problem+json 384 Required parameters: None 385 Optional parameters: None; unrecognised parameters 386 should be ignored 387 Encoding considerations: Same as [RFC4627] 388 Security considerations: see [this document] 389 Interoperability considerations: None. 390 Published specification: [this document] 391 Applications that use this media type: HTTP 392 Additional information: 393 Magic number(s): n/a 394 File extension(s): n/a 395 Macintosh file type code(s): n/a 396 Person & email address to contact for further information: 397 Mark Nottingham 398 Intended usage: COMMON 399 Restrictions on usage: None. 400 Author: Mark Nottingham 401 Change controller: IESG 402 Type name: application 403 Subtype name: problem+xml 404 Required parameters: None 405 Optional parameters: None; unrecognized parameters 406 should be ignored 407 Encoding considerations: Same as [RFC3023] 408 Security considerations: see [this document] 409 Interoperability considerations: None. 410 Published specification: [this document] 411 Applications that use this media type: HTTP 412 Additional information: 413 Magic number(s): n/a 414 File extension(s): n/a 415 Macintosh file type code(s): n/a 416 Person & email address to contact for further information: 417 Mark Nottingham 418 Intended usage: COMMON 419 Restrictions on usage: None. 420 Author: Mark Nottingham 421 Change controller: IESG 423 8. Acknowledgements 425 The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu 426 Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, 427 Julian Reschke, and James Snell for review of this specification. 429 9. References 431 9.1. Normative References 433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 434 Requirement Levels", BCP 14, RFC 2119, March 1997. 436 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 437 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 438 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 440 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 441 Resource Identifier (URI): Generic Syntax", STD 66, 442 RFC 3986, January 2005. 444 [RFC4627] Crockford, D., "The application/json Media Type for 445 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 447 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 448 Specifications: ABNF", STD 68, RFC 5234, January 2008. 450 9.2. Informative References 452 [ISO-19757-2] 453 International Organization for Standardization, 454 "Information Technology --- Document Schema Definition 455 Languages (DSDL) --- Part 2: Grammar-based Validation --- 456 RELAX NG", ISO/IEC 19757-2, 2003. 458 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 459 Types", RFC 3023, January 2001. 461 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 463 [RFC6694] Moonesamy, S., "The "about" URI Scheme", RFC 6694, 464 August 2012. 466 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 467 Specifications and Registration Procedures", BCP 13, 468 RFC 6838, January 2013. 470 [W3C.REC-html401-19991224] 471 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 472 Specification", World Wide Web Consortium 473 Recommendation REC-html401-19991224, December 1999, 474 . 476 [W3C.REC-rdfa-core-20120607] 477 Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa 478 Core 1.1", World Wide Web Consortium Recommendation REC- 479 rdfa-core-20120607, June 2012, 480 . 482 [W3C.REC-xml-20081126] 483 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 484 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 485 Edition)", World Wide Web Consortium Recommendation REC- 486 xml-20081126, November 2008, 487 . 489 URIs 491 [1] 493 Appendix A. HTTP Problems and XML 495 Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary 496 format convention. Such APIs MAY express problem details using the 497 format defined in this appendix. 499 The OPTIONAL RELAX NG schema [ISO-19757-2] for the XML format is: 501 default namespace ns = "urn:ietf:rfc:XXXX" 503 start = problem 505 problem = 506 element problem { 507 ( element type { xsd:anyURI } 508 & element title { xsd:string } 509 & element detail { xsd:string }? 510 & element status { xsd:positiveInteger }? 511 & element instance { xsd:anyURI }? ), 512 anyNsElement 513 } 515 anyNsElement = 516 ( element ns:* { anyNsElement | text } 517 | attribute * { text })* 519 The media type for this format is "application/problem+xml". 521 Extension arrays and objects can be serialized into the XML format by 522 considering an element containing a child or children to represent an 523 object, except for elements that contain only child element(s) named 524 'i', which are considered arrays. For example, an alternate version 525 of the example above would appear in XML as: 527 HTTP/1.1 403 Forbidden 528 Content-Type: application/problem+xml 529 Content-Language: en 531 532 533 http://example.com/probs/out-of-credit 534 You do not have enough credit. 535 Your current balance is 30, but that costs 50. 536 537 http://example.net/account/12345/msgs/abc 538 539 30 540 541 http://example.net/account/12345 542 http://example.net/account/67890 543 544 546 Note that this format uses an XML Namespace. This is primarily to 547 allow embedding it into other formats; it does not imply that it can 548 be extended with content from other namespaces. The RELAX NG schema 549 explicitly only allows elements from the one namespace used in the 550 XML format. Any extension arrays and objects MUST be serialized into 551 XML markup using that namespace. 553 Authors' Addresses 555 Mark Nottingham 556 Akamai 558 Email: mnot@mnot.net 559 URI: http://www.mnot.net/ 561 Erik Wilde 562 EMC 563 6801 Koll Center Parkway 564 Pleasanton, CA 94566 565 U.S.A. 567 Phone: +1-925-6006244 568 Email: erik.wilde@emc.com 569 URI: http://dret.net/netdret/