idnits 2.17.00 (12 Aug 2021) /tmp/idnits46052/draft-ietf-appsawg-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 == Line 535 has weird spacing: '...element type ...' == Line 536 has weird spacing: '...element title...' == Line 537 has weird spacing: '...element detai...' == Line 538 has weird spacing: '...element statu...' == Line 539 has weird spacing: '...element insta...' == (1 more instance...) -- The document date (September 7, 2015) is 2447 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 19 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 2 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: Standards Track E. Wilde 5 Expires: March 10, 2016 UC Berkeley 6 September 7, 2015 8 Problem Details for HTTP APIs 9 draft-ietf-appsawg-http-problem-01 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 March 10, 2016. 38 Copyright Notice 40 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4 58 3.1. Problem Details Object Members . . . . . . . . . . . . . 5 59 3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6 60 4. Defining New Problem Types . . . . . . . . . . . . . . . . . 6 61 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 8 63 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 65 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 66 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 68 8.2. Informative References . . . . . . . . . . . . . . . . . 11 69 Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 12 70 Appendix B. Using Problem Details with Other Formats . . . . . . 14 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 73 1. Introduction 75 HTTP [RFC7230] status codes are sometimes not sufficient to convey 76 enough information about an error to be helpful. While humans behind 77 Web browsers can be informed about the nature of the problem with an 78 HTML [W3C.REC-html401-19991224] response body, non-human consumers of 79 so-called "HTTP APIs" are usually not. 81 This specification defines simple JSON [RFC7159] and XML 82 [W3C.REC-xml-20081126] document formats to suit this purpose. They 83 are designed to be reused by HTTP APIs, which can identify distinct 84 "problem types" specific to their needs. 86 Thus, API clients can be informed of both the high-level error class 87 (using the status code) and the finer-grained details of the problem 88 (using one of these formats). 90 For example, consider a response that indicates that the client's 91 account doesn't have enough credit. The 403 Forbidden status code 92 might be deemed most appropriate to use, as it will inform HTTP- 93 generic software (such as client libraries, caches and proxies) of 94 the general semantics of the response. 96 However, that doesn't give the API client enough information about 97 why the request was forbidden, the applicable account balance, or how 98 to correct the problem. If these details are included in the 99 response body in a machine-readable format, the client can treat it 100 appropriately; for example, triggering a transfer of more credit into 101 the account. 103 This specification does this by identifying a specific type of 104 problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can 105 do this by nominating new URIs under their control, or by reusing 106 existing ones. 108 Additionally, problems can contain other information, such as a URI 109 that identifies the specific occurrence of the problem (effectively 110 giving an identifier to the concept "The time Joe didn't have enough 111 credit last Thursday"), which can be useful for support or forensic 112 purposes. 114 The data model for problem details is a JSON [RFC7159] object; when 115 formatted as a JSON document, it uses the "application/problem+json" 116 media type. Appendix A defines how to express them in an equivalent 117 XML format, which uses the "application/problem+xml" media type. 119 Note that problem details are (naturally) not the only way to convey 120 the details of a problem in HTTP; if the response is still a 121 representation of a resource, for example, it's often preferable to 122 accommodate describing the relevant details in that application's 123 format. Likewise, in many situations, there is an appropriate HTTP 124 status code that does not require extra detail to be conveyed. 126 Instead, the aim of this specification is to define common error 127 formats for those applications that need one, so that they aren't 128 required to define their own, or worse, tempted to re-define the 129 semantics of existing HTTP status codes. Even if an application 130 chooses not to use it to convey errors, reviewing its design can help 131 guide the design decisions faced when conveying errors in an existing 132 format. 134 2. Requirements 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 138 document are to be interpreted as described in [RFC2119]. 140 3. The Problem Details JSON Object 142 The canonical model for problem details is a JSON [RFC7159] object. 144 When serialised as a JSON document, that format is identified with 145 the "application/problem+json" media type. 147 For example, a HTTP response carrying JSON problem details: 149 HTTP/1.1 403 Forbidden 150 Content-Type: application/problem+json 151 Content-Language: en 153 { 154 "type": "https://example.com/probs/out-of-credit", 155 "title": "You do not have enough credit.", 156 "detail": "Your current balance is 30, but that costs 50.", 157 "instance": "/account/12345/msgs/abc", 158 "balance": 30, 159 "accounts": ["/account/12345", 160 "/account/67890"] 161 } 163 Here, the out-of-credit problem (identified by its type URI) 164 indicates the reason for the 403 in "title", gives a reference for 165 the specific problem occurrence with "instance", gives occurrence- 166 specific details in "detail", and adds two extensions; "balance" 167 conveys the account's balance, and "accounts" gives links where the 168 account can be topped up. 170 The ability to convey problem-specific extensions allows more than 171 one problem to be conveyed. For example: 173 HTTP/1.1 400 Bad Request 174 Content-Type: application/problem+json 175 Content-Language: en 177 { 178 "type": "https://example.net/validation-error", 179 "title": "Your request parameters didn't validate.", 180 "invalid-params": [ { 181 "name": "age", 182 "reason": "must be a positive integer" 183 }, 184 { 185 "name": "color", 186 "reason": "must be 'green', 'red' or 'blue'"} 187 ] 188 } 190 Note that this requires each of the sub-problems to be similar enough 191 to use the same HTTP status code. If they do not, the 207 (Multi- 192 Status) [RFC4918] code could be used to encapsulate multiple status 193 messages. 195 3.1. Problem Details Object Members 197 A problem details object MAY have the following members: 199 o "type" (string) - A URI reference [RFC3986] that identifies the 200 problem type. When dereferenced, it is encouraged to provide 201 human-readable documentation for the problem type (e.g., using 202 HTML [W3C.REC-html401-19991224]). When this member is not 203 present, its value is assumed to be "about:blank". 205 o "title" (string) - A short, human-readable summary of the problem 206 type. It SHOULD NOT change from occurrence to occurrence of the 207 problem, except for purposes of localisation. 209 o "status" (number) - The HTTP status code ([RFC7231], Section 6) 210 generated by the origin server for this occurrence of the problem. 212 o "detail" (string) - An human readable explanation specific to this 213 occurrence of the problem. 215 o "instance" (string) - A URI reference that identifies the specific 216 occurrence of the problem. It may or may not yield further 217 information if dereferenced. 219 Consumers MUST use the type string as the primary identifier for the 220 problem type; the title string is advisory, and included only for 221 users who are not aware of the semantics of the URI, and don't have 222 the ability to discover them (e.g., offline log analysis). Consumers 223 SHOULD NOT automatically dereference the type URI. 225 The status member, if present, is only advisory; it conveys the HTTP 226 status code used for the convenience of the consumer. Generators 227 MUST use the same status code in the actual HTTP response, to assure 228 that generic HTTP software that does not understand this format still 229 behaves correctly. See Section 5 for further caveats regarding its 230 use. 232 The detail member, if present, SHOULD focus on helping the client 233 correct the problem, rather than giving debugging information. 235 Consumers SHOULD NOT parse the detail member for information; 236 extensions are more suitable and less error-prone ways to obtain such 237 information. 239 Note that both "type" and "instance" accept relative URIs; this means 240 that they must be resolved relative to the document's base URI, as 241 per {{RFC3986}}, Section 5. 243 3.2. Extension Members 245 Problem type definitions MAY extend the problem details object with 246 additional members. 248 For example, our "out of credit" problem above defines two such 249 extensions, "balance" and "accounts" to convey additional, problem- 250 specific information. 252 Clients consuming problem details MUST ignore any such extensions 253 that they don't recognise; this allows problem types to evolve and 254 include additional information in the future. 256 Note that because extensions are effectively name spaced by the 257 problem type, it is not possible to define new "standard" members 258 without defining a new media type. 260 4. Defining New Problem Types 262 When an HTTP API needs to define a response that indicates an error 263 condition, it might be appropriate to do so by defining a new problem 264 type. 266 Before doing so, it's important to understand what they are good for, 267 and what's better left to other mechanisms. 269 Problem details are not a debugging tool for the underlying 270 implementation; rather, they are a way to expose greater detail about 271 the HTTP interface itself. New problem types need to carefully 272 consider the Security Considerations (Section 5); in particular the 273 risk of exposing attack vectors by exposing implementation internals 274 through error messages. 276 Likewise, truly generic problems - i.e., conditions that could 277 potentially apply to any resource on the Web - are usually better 278 expressed as plain status codes. For example, a "write access 279 disallowed" problem is probably unnecessary, since a 403 Forbidden 280 status code in response to a PUT request is self-explanatory. 282 Finally, an application may have a more appropriate way to carry an 283 error in a format that it already defines. Problem details are 284 intended to avoid the necessity of establishing new "fault" or 285 "error" document formats, not to replace existing domain-specific 286 formats. 288 That said, it is possible to add support for problem details to 289 existing HTTP APIs using HTTP content negotiation (e.g., using the 290 Accept request header to indicate a preference for this format). 292 New problem type definitions MUST document: 294 1. A type URI (typically, with the "http" scheme), 296 2. A title that appropriately describes it (think short), and 298 3. The HTTP status code for it to be used with. 300 Problem types MAY specify the use of the Retry-After response header 301 in appropriate circumstances. 303 A problem's type URI SHOULD resolve to HTML 304 [W3C.REC-html401-19991224] documentation that explains how to resolve 305 the problem. 307 A problem type definition MAY specify additional members on the 308 Problem Details object. For example, an extension might use typed 309 links [RFC5988] to another resource that can be used by machines to 310 resolve the problem. 312 If such additional members are defined, their names SHOULD start with 313 a letter (ALPHA, as per [RFC5234]) and SHOULD consist of characters 314 from ALPHA, DIGIT, and "_" (so that it can be serialized in formats 315 other than JSON), and SHOULD be three characters or longer. 317 4.1. Example 319 For example, if you are publishing an HTTP API to your online 320 shopping cart, you might need to indicate that the user is out of 321 credit (our example from above), and therefore cannot make the 322 purchase. 324 If you already have an application-specific format that can 325 accommodate this information, it's probably best to do that. 326 However, if you don't, you might consider using one of the problem 327 details formats; JSON if your API is JSON-based, or XML if it uses 328 that format. 330 To do so, you might look for an already-defined type URI that suits 331 your purposes. If one is available, you can reuse that URI. 333 If one isn't available, you could mint and document a new type URI 334 (which ought to be under your control and stable over time), an 335 appropriate title and the HTTP status code that it will be used with, 336 along with what it means and how it should be handled. 338 In summary: an instance URI will always identify a specific 339 occurrence of a problem. On the other hand, type URIs can be reused 340 if an appropriate description of a problem type is already available 341 someplace else, or they can be created for new problem types. 343 4.2. Pre-Defined Problem Types 345 This specification reserves the use of one URI as a problem type: 347 The "about:blank" URI [RFC6694], when used as a problem type, 348 indicates that the problem has no additional semantics beyond that of 349 the HTTP status code. 351 When "about:blank" is used, the title SHOULD be the same as the 352 recommended HTTP status phrase for that code (e.g., "Not Found" for 353 404, and so on), although it MAY be localized to suit client 354 preferences (expressed with the Accept-Language request header). 356 Please note that according to how the "type" member is defined 357 (Section 3.1), the "about:blank" URI is the default value for that 358 member. Consequently, any problem details object not carrying an 359 explicit "type" member implicitly uses this URI. 361 5. Security Considerations 363 When defining a new problem type, the information included must be 364 carefully vetted. Likewise, when actually generating a problem - 365 however it is serialized - the details given must also be 366 scrutinized. 368 Risks include leaking information that can be exploited to compromise 369 the system, access to the system, or the privacy of users of the 370 system. 372 Generators providing links to occurrence information are encouraged 373 to avoid making implementation details such as a stack dump available 374 through the HTTP interface, since this can expose sensitive details 375 of the server implementation, its data, and so on. 377 The "status" member duplicates the information available in the HTTP 378 status code itself, thereby bringing the possibility of disagreement 379 between the two. Their relative precedence is not clear, since a 380 disagreement might indicate that (for example) an intermediary has 381 modified the HTTP status code in transit. As such, those defining 382 problem types as well as generators and consumers of problems need to 383 be aware that generic software (such as proxies, load balancers, 384 firewalls, virus scanners) are unlikely to know of or respect the 385 status code conveyed in this member. 387 6. IANA Considerations 389 This specification defines two new Internet media types [RFC6838]: 391 Type name: application 392 Subtype name: problem+json 393 Required parameters: None 394 Optional parameters: None; unrecognised parameters 395 should be ignored 396 Encoding considerations: Same as [RFC7159] 397 Security considerations: see [this document] 398 Interoperability considerations: None. 399 Published specification: [this document] 400 Applications that use this media type: HTTP 401 Additional information: 402 Magic number(s): n/a 403 File extension(s): n/a 404 Macintosh file type code(s): n/a 405 Person & email address to contact for further information: 406 Mark Nottingham 407 Intended usage: COMMON 408 Restrictions on usage: None. 409 Author: Mark Nottingham 410 Change controller: IESG 412 Type name: application 413 Subtype name: problem+xml 414 Required parameters: None 415 Optional parameters: None; unrecognized parameters 416 should be ignored 417 Encoding considerations: Same as [RFC7303] 418 Security considerations: see [this document] 419 Interoperability considerations: None. 420 Published specification: [this document] 421 Applications that use this media type: HTTP 422 Additional information: 423 Magic number(s): n/a 424 File extension(s): n/a 425 Macintosh file type code(s): n/a 426 Person & email address to contact for further information: 427 Mark Nottingham 428 Intended usage: COMMON 429 Restrictions on usage: None. 430 Author: Mark Nottingham 431 Change controller: IESG 433 7. Acknowledgements 435 The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu 436 Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, 437 Julian Reschke, and James Snell for review of this specification. 439 8. References 441 8.1. Normative References 443 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 444 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 445 RFC2119, March 1997, 446 . 448 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 449 Resource Identifier (URI): Generic Syntax", STD 66, RFC 450 3986, DOI 10.17487/RFC3986, January 2005, 451 . 453 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 454 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 455 RFC5234, January 2008, 456 . 458 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 459 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 460 2014, . 462 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 463 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 464 7230, DOI 10.17487/RFC7230, June 2014, 465 . 467 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 468 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 469 10.17487/RFC7231, June 2014, 470 . 472 8.2. Informative References 474 [ISO-19757-2] 475 International Organization for Standardization, 476 "Information Technology --- Document Schema Definition 477 Languages (DSDL) --- Part 2: Grammar-based Validation --- 478 RELAX NG", ISO/IEC 19757-2, 2003. 480 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 481 Authoring and Versioning (WebDAV)", RFC 4918, DOI 482 10.17487/RFC4918, June 2007, 483 . 485 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ 486 RFC5988, October 2010, 487 . 489 [RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694, 490 DOI 10.17487/RFC6694, August 2012, 491 . 493 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 494 Specifications and Registration Procedures", BCP 13, RFC 495 6838, DOI 10.17487/RFC6838, January 2013, 496 . 498 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, 499 DOI 10.17487/RFC7303, July 2014, 500 . 502 [W3C.REC-html401-19991224] 503 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 504 Specification", World Wide Web Consortium Recommendation 505 REC-html401-19991224, December 1999, 506 . 508 [W3C.REC-rdfa-core-20120607] 509 Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa 510 Core 1.1", World Wide Web Consortium Recommendation REC- 511 rdfa-core-20120607, June 2012, 512 . 514 [W3C.REC-xml-20081126] 515 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 516 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 517 Edition)", World Wide Web Consortium Recommendation REC- 518 xml-20081126, November 2008, 519 . 521 Appendix A. HTTP Problems and XML 523 Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary 524 format convention. Such APIs MAY express problem details using the 525 format defined in this appendix. 527 The OPTIONAL RELAX NG schema [ISO-19757-2] for the XML format is: 529 default namespace ns = "urn:ietf:rfc:XXXX" 531 start = problem 533 problem = 534 element problem { 535 ( element type { xsd:anyURI }? 536 & element title { xsd:string }? 537 & element detail { xsd:string }? 538 & element status { xsd:positiveInteger }? 539 & element instance { xsd:anyURI }? ), 540 anyNsElement 541 } 543 anyNsElement = 544 ( element ns:* { anyNsElement | text } 545 | attribute * { text })* 547 The media type for this format is "application/problem+xml". 549 Extension arrays and objects can be serialized into the XML format by 550 considering an element containing a child or children to represent an 551 object, except for elements that contain only child element(s) named 552 'i', which are considered arrays. For example, an alternate version 553 of the example above would appear in XML as: 555 HTTP/1.1 403 Forbidden 556 Content-Type: application/problem+xml 557 Content-Language: en 559 560 561 https://example.com/probs/out-of-credit 562 You do not have enough credit. 563 Your current balance is 30, but that costs 50. 564 565 https://example.net/account/12345/msgs/abc 566 567 30 568 569 https://example.net/account/12345 570 https://example.net/account/67890 571 572 574 Note that this format uses an XML Namespace. This is primarily to 575 allow embedding it into other XML-based formats; it does not imply 576 that it can or should be extended with elements or attributes in 577 other namespaces. The RELAX NG schema explicitly only allows 578 elements from the one namespace used in the XML format. Any 579 extension arrays and objects MUST be serialized into XML markup using 580 only that namespace. 582 Appendix B. Using Problem Details with Other Formats 584 In some situations, it can be advantageous to embed Problem Details 585 in formats other than those described here. For example, an API that 586 uses HTML [W3C.REC-html401-19991224] might want to also use HTML for 587 expressing its problem details. 589 Problem details can be embedded in other formats by either 590 encapsulating one of the existing serializations (JSON or XML) into 591 that format, or by translating the model of a Problem Detail (as 592 specified in Section 3) into the format's conventions. 594 For example, in HTML, a problem could be embedded by encapsulating 595 JSON in a script tag: 597 608 } 610 or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20120607]. 612 This specification does not make specific recommendations regarding 613 embedding Problem Details in other formats; the appropriate way to 614 embed them depends both upon the format in use and application of 615 that format. 617 Authors' Addresses 619 Mark Nottingham 620 Akamai 622 Email: mnot@mnot.net 623 URI: http://www.mnot.net/ 624 Erik Wilde 625 UC Berkeley 627 Email: dret@berkeley.edu 628 URI: http://dret.net/netdret/