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/