idnits 2.17.1 draft-ietf-appsawg-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 : ---------------------------------------------------------------------------- ** 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 483 has weird spacing: '...element type ...' == Line 484 has weird spacing: '...element title...' == Line 485 has weird spacing: '...element detai...' == Line 486 has weird spacing: '...element statu...' == Line 487 has weird spacing: '...element insta...' == (1 more instance...) -- The document date (September 19, 2014) is 3507 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 normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 4 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 23, 2015 UC Berkeley 6 September 19, 2014 8 Problem Details for HTTP APIs 9 draft-ietf-appsawg-http-problem-00 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 23, 2015. 38 Copyright Notice 40 Copyright (c) 2014 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 . . . . . . . . . . . . . 4 59 3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 5 60 4. Defining New Problem Types . . . . . . . . . . . . . . . . . 5 61 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 7 63 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 65 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 66 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 68 8.2. Informative References . . . . . . . . . . . . . . . . . 10 69 Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 11 70 Appendix B. Using Problem Details with Other Formats . . . . . . 12 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 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 may 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": "http://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": "http://example.net/account/12345/msgs/abc", 158 "balance": 30, 159 "accounts": ["http://example.net/account/12345", 160 "http://example.net/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 3.1. Problem Details Object Members 172 A problem details object MAY have the following members: 174 o "type" (string) - An absolute URI [RFC3986] that identifies the 175 problem type. When dereferenced, it SHOULD provide human-readable 176 documentation for the problem type (e.g., using HTML 177 [W3C.REC-html401-19991224]). When this member is not present, its 178 value is assumed to be "about:blank". 180 o "title" (string) - A short, human-readable summary of the problem 181 type. It SHOULD NOT change from occurrence to occurrence of the 182 problem, except for purposes of localisation. 184 o "status" (number) - The HTTP status code ([RFC7231], Section 6) 185 generated by the origin server for this occurrence of the problem. 187 o "detail" (string) - An human readable explanation specific to this 188 occurrence of the problem. 190 o "instance" (string) - An absolute URI that identifies the specific 191 occurrence of the problem. It may or may not yield further 192 information if dereferenced. 194 Consumers MUST use the type string as the primary identifier for the 195 problem type; the title string is advisory, and included only for 196 users who are not aware of the semantics of the URI, and don't have 197 the ability to discover them (e.g., offline log analysis). Consumers 198 SHOULD NOT automatically dereference the type URI. 200 The status member, if present, is only advisory; it conveys the HTTP 201 status code used for the convenience of the consumer. Generators 202 MUST use the same status code in the actual HTTP response, to assure 203 that generic HTTP software that does not understand this format still 204 behaves correctly. See Section 5 for further caveats regarding its 205 use. 207 The detail member, if present, SHOULD focus on helping the client 208 correct the problem, rather than giving debugging information. 210 Consumers SHOULD NOT parse the detail member for information; 211 extensions are more suitable and less error-prone ways to obtain such 212 information. 214 3.2. Extension Members 216 Problem type definitions MAY extend the problem details object with 217 additional members. 219 For example, our "out of credit" problem above defines two such 220 extensions, "balance" and "accounts" to convey additional, problem- 221 specific information. 223 Clients consuming problem details MUST ignore any such extensions 224 that they don't recognise; this allows problem types to evolve and 225 include additional information in the future. 227 4. Defining New Problem Types 229 When an HTTP API needs to define a response that indicates an error 230 condition, it might be appropriate to do so by defining a new problem 231 type. 233 Before doing so, it's important to understand what they are good for, 234 and what's better left to other mechanisms. 236 Problem details are not a debugging tool for the underlying 237 implementation; rather, they are a way to expose greater detail about 238 the HTTP interface itself. New problem types need to carefully 239 consider the Security Considerations (Section 5); in particular the 240 risk of exposing attack vectors by exposing implementation internals 241 through error messages. 243 Likewise, truly generic problems - i.e., conditions that could 244 potentially apply to any resource on the Web - are usually better 245 expressed as plain status codes. For example, a "write access 246 disallowed" problem is probably unnecessary, since a 403 Forbidden 247 status code in response to a PUT request is self-explanatory. 249 Finally, an application may have a more appropriate way to carry an 250 error in a format that it already defines. Problem details are 251 intended to avoid the necessity of establishing new "fault" or 252 "error" document formats, not to replace existing domain-specific 253 formats. 255 That said, it is possible to add support for problem details to 256 existing HTTP APIs using HTTP content negotiation (e.g., using the 257 Accept request header to indicate a preference for this format). 259 New problem type definitions MUST document: 261 1. A type URI (typically, with the "http" scheme), 263 2. A title that appropriately describes it (think short), and 265 3. The HTTP status code for it to be used with. 267 Problem types MAY specify the use of the Retry-After response header 268 in appropriate circumstances. 270 A problem's type URI SHOULD resolve to HTML 271 [W3C.REC-html401-19991224] documentation that explains how to resolve 272 the problem. 274 A problem type definition MAY specify additional members on the 275 Problem Details object. For example, an extension might use typed 276 links [RFC5988] to another resource that can be used by machines to 277 resolve the problem. 279 If such additional members are defined, their names SHOULD start with 280 a letter (ALPHA, as per [RFC5234]) and SHOULD consist of characters 281 from ALPHA, DIGIT, and "_" (so that it can be serialized in formats 282 other than JSON), and SHOULD be three characters or longer. 284 4.1. Example 286 For example, if you are publishing an HTTP API to your online 287 shopping cart, you might need to indicate that the user is out of 288 credit (our example from above), and therefore cannot make the 289 purchase. 291 If you already have an application-specific format that can 292 accommodate this information, it's probably best to do that. 293 However, if you don't, you might consider using one of the problem 294 details formats; JSON if your API is JSON-based, or XML if it uses 295 that format. 297 To do so, you might look for an already-defined type URI that suits 298 your purposes. If one is available, you can reuse that URI. 300 If one isn't available, you could mint and document a new type URI 301 (which ought to be under your control and stable over time), an 302 appropriate title and the HTTP status code that it will be used with, 303 along with what it means and how it should be handled. 305 In summary: an instance URI will always identify a specific 306 occurrence of a problem. On the other hand, type URIs can be reused 307 if an appropriate description of a problem type is already available 308 someplace else, or they can be created for new problem types. 310 4.2. Pre-Defined Problem Types 312 This specification reserves the use of one URI as a problem type: 314 The "about:blank" URI [RFC6694], when used as a problem type, 315 indicates that the problem has no additional semantics beyond that of 316 the HTTP status code. 318 When "about:blank" is used, the title SHOULD be the same as the 319 recommended HTTP status phrase for that code (e.g., "Not Found" for 320 404, and so on), although it MAY be localized to suit client 321 preferences (expressed with the Accept-Language request header). 323 Please note that according to how the "type" member is defined 324 (Section 3.1), the "about:blank" URI is the default value for that 325 member. Consequently, any problem details object not carrying an 326 explicit "type" member implicitly uses this URI. 328 5. Security Considerations 330 When defining a new problem type, the information included must be 331 carefully vetted. Likewise, when actually generating a problem - 332 however it is serialized - the details given must also be 333 scrutinized. 335 Risks include leaking information that can be exploited to compromise 336 the system, access to the system, or the privacy of users of the 337 system. 339 Generators providing links to occurrence information are encouraged 340 to avoid making implementation details such as a stack dump available 341 through the HTTP interface, since this can expose sensitive details 342 of the server implementation, its data, and so on. 344 The "status" member duplicates the information available in the HTTP 345 status code itself, thereby bringing the possibility of disagreement 346 between the two. Their relative precedence is not clear, since a 347 disagreement might indicate that (for example) an intermediary has 348 modified the HTTP status code in transit. As such, those defining 349 problem types as well as generators and consumers of problems need to 350 be aware that generic software (such as proxies, load balancers, 351 firewalls, virus scanners) are unlikely to know of or respect the 352 status code conveyed in this member. 354 6. IANA Considerations 356 This specification defines two new Internet media types [RFC6838]: 358 Type name: application 359 Subtype name: problem+json 360 Required parameters: None 361 Optional parameters: None; unrecognised parameters 362 should be ignored 363 Encoding considerations: Same as [RFC7159] 364 Security considerations: see [this document] 365 Interoperability considerations: None. 366 Published specification: [this document] 367 Applications that use this media type: HTTP 368 Additional information: 369 Magic number(s): n/a 370 File extension(s): n/a 371 Macintosh file type code(s): n/a 372 Person & email address to contact for further information: 373 Mark Nottingham 374 Intended usage: COMMON 375 Restrictions on usage: None. 376 Author: Mark Nottingham 377 Change controller: IESG 379 Type name: application 380 Subtype name: problem+xml 381 Required parameters: None 382 Optional parameters: None; unrecognized parameters 383 should be ignored 384 Encoding considerations: Same as [RFC7303] 385 Security considerations: see [this document] 386 Interoperability considerations: None. 387 Published specification: [this document] 388 Applications that use this media type: HTTP 389 Additional information: 390 Magic number(s): n/a 391 File extension(s): n/a 392 Macintosh file type code(s): n/a 393 Person & email address to contact for further information: 394 Mark Nottingham 395 Intended usage: COMMON 396 Restrictions on usage: None. 397 Author: Mark Nottingham 398 Change controller: IESG 400 7. Acknowledgements 402 The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu 403 Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, 404 Julian Reschke, and James Snell for review of this specification. 406 8. References 408 8.1. Normative References 410 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 411 Requirement Levels", BCP 14, RFC 2119, March 1997. 413 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 414 Resource Identifier (URI): Generic Syntax", STD 66, RFC 415 3986, January 2005. 417 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 418 Specifications: ABNF", STD 68, RFC 5234, January 2008. 420 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 421 Interchange Format", RFC 7159, March 2014. 423 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 424 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 425 2014. 427 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 428 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 430 8.2. Informative References 432 [ISO-19757-2] 433 International Organization for Standardization, 434 "Information Technology --- Document Schema Definition 435 Languages (DSDL) --- Part 2: Grammar-based Validation --- 436 RELAX NG", ISO/IEC 19757-2, 2003. 438 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 440 [RFC6694] Moonesamy, S., "The "about" URI Scheme", RFC 6694, August 441 2012. 443 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 444 Specifications and Registration Procedures", BCP 13, RFC 445 6838, January 2013. 447 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, 448 July 2014. 450 [W3C.REC-html401-19991224] 451 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 452 Specification", World Wide Web Consortium Recommendation 453 REC-html401-19991224, December 1999, 454 . 456 [W3C.REC-rdfa-core-20120607] 457 Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa 458 Core 1.1", World Wide Web Consortium Recommendation REC- 459 rdfa-core-20120607, June 2012, 460 . 462 [W3C.REC-xml-20081126] 463 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 464 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 465 Edition)", World Wide Web Consortium Recommendation REC- 466 xml-20081126, November 2008, 467 . 469 Appendix A. HTTP Problems and XML 471 Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary 472 format convention. Such APIs MAY express problem details using the 473 format defined in this appendix. 475 The OPTIONAL RELAX NG schema [ISO-19757-2] for the XML format is: 477 default namespace ns = "urn:ietf:rfc:XXXX" 479 start = problem 481 problem = 482 element problem { 483 ( element type { xsd:anyURI }? 484 & element title { xsd:string }? 485 & element detail { xsd:string }? 486 & element status { xsd:positiveInteger }? 487 & element instance { xsd:anyURI }? ), 488 anyNsElement 489 } 491 anyNsElement = 492 ( element ns:* { anyNsElement | text } 493 | attribute * { text })* 495 The media type for this format is "application/problem+xml". 497 Extension arrays and objects can be serialized into the XML format by 498 considering an element containing a child or children to represent an 499 object, except for elements that contain only child element(s) named 500 'i', which are considered arrays. For example, an alternate version 501 of the example above would appear in XML as: 503 HTTP/1.1 403 Forbidden 504 Content-Type: application/problem+xml 505 Content-Language: en 507 508 509 http://example.com/probs/out-of-credit 510 You do not have enough credit. 511 Your current balance is 30, but that costs 50. 512 513 http://example.net/account/12345/msgs/abc 514 515 30 516 517 http://example.net/account/12345 518 http://example.net/account/67890 519 520 522 Note that this format uses an XML Namespace. This is primarily to 523 allow embedding it into other XML-based formats; it does not imply 524 that it can or should be extended with elements or attributes in 525 other namespaces. The RELAX NG schema explicitly only allows 526 elements from the one namespace used in the XML format. Any 527 extension arrays and objects MUST be serialized into XML markup using 528 only that namespace. 530 Appendix B. Using Problem Details with Other Formats 532 In some situations, it can be advantageous to embed Problem Details 533 in formats other than those described here. For example, an API that 534 uses HTML [W3C.REC-html401-19991224] might want to also use HTML for 535 expressing its problem details. 537 Problem details can be embedded in other formats by either 538 encapsulating one of the existing serializations (JSON or XML) into 539 that format, or by translating the model of a Problem Detail (as 540 specified in Section 3) into the format's conventions. 542 For example, in HTML, a problem could be embedded by encapsulating 543 JSON in a script tag: 545 556 } 558 or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20120607]. 560 This specification does not make specific recommendations regarding 561 embedding Problem Details in other formats; the appropriate way to 562 embed them depends both upon the format in use and application of 563 that format. 565 Authors' Addresses 567 Mark Nottingham 568 Akamai 570 Email: mnot@mnot.net 571 URI: http://www.mnot.net/ 573 Erik Wilde 574 UC Berkeley 576 Email: dret@berkeley.edu 577 URI: http://dret.net/netdret/