| < draft-ietf-httpapi-rfc7807bis-01.txt | draft-ietf-httpapi-rfc7807bis-02.txt > | |||
|---|---|---|---|---|
| HTTPAPI M. Nottingham | HTTPAPI M. Nottingham | |||
| Internet-Draft | Internet-Draft | |||
| Obsoletes: 7807 (if approved) E. Wilde | Obsoletes: 7807 (if approved) E. Wilde | |||
| Intended status: Standards Track | Intended status: Standards Track | |||
| Expires: 16 April 2022 S. Dalal | Expires: 18 October 2022 S. Dalal | |||
| 13 October 2021 | 16 April 2022 | |||
| Problem Details for HTTP APIs | Problem Details for HTTP APIs | |||
| draft-ietf-httpapi-rfc7807bis-01 | draft-ietf-httpapi-rfc7807bis-02 | |||
| Abstract | Abstract | |||
| This document defines a "problem detail" as a way to carry machine- | This document defines a "problem detail" to carry machine-readable | |||
| readable details of errors in a HTTP response to avoid the need to | details of errors in a HTTP response to avoid the need to define new | |||
| define new error response formats for HTTP APIs. | error response formats for HTTP APIs. | |||
| Discussion Venues | Discussion Venues | |||
| This note is to be removed before publishing as an RFC. | This note is to be removed before publishing as an RFC. | |||
| Source for this draft and an issue tracker can be found at | Source for this draft and an issue tracker can be found at | |||
| https://github.com/ietf-wg-httpapi/rfc7807bis. | https://github.com/ietf-wg-httpapi/rfc7807bis. | |||
| Status of This Memo | Status of This Memo | |||
| skipping to change at page 1, line 41 ¶ | skipping to change at page 1, line 41 ¶ | |||
| Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
| Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
| working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
| Drafts is at https://datatracker.ietf.org/drafts/current/. | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
| Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
| and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
| time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
| material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
| This Internet-Draft will expire on 16 April 2022. | This Internet-Draft will expire on 18 October 2022. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (c) 2021 IETF Trust and the persons identified as the | Copyright (c) 2022 IETF Trust and the persons identified as the | |||
| document authors. All rights reserved. | document authors. All rights reserved. | |||
| This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
| Provisions Relating to IETF Documents (https://trustee.ietf.org/ | Provisions Relating to IETF Documents (https://trustee.ietf.org/ | |||
| license-info) in effect on the date of publication of this document. | license-info) in effect on the date of publication of this document. | |||
| Please review these documents carefully, as they describe your rights | Please review these documents carefully, as they describe your rights | |||
| and restrictions with respect to this document. Code Components | and restrictions with respect to this document. Code Components | |||
| extracted from this document must include Simplified BSD License text | extracted from this document must include Revised BSD License text as | |||
| as described in Section 4.e of the Trust Legal Provisions and are | described in Section 4.e of the Trust Legal Provisions and are | |||
| provided without warranty as described in the Simplified BSD License. | provided without warranty as described in the Revised BSD License. | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | |||
| 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 4 | 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4 | 3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4 | |||
| 3.1. Members of a Problem Details Object . . . . . . . . . . . 5 | 3.1. Members of a Problem Details Object . . . . . . . . . . . 5 | |||
| 3.1.1. "type" . . . . . . . . . . . . . . . . . . . . . . . 5 | 3.1.1. "type" . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
| 3.1.2. "status" . . . . . . . . . . . . . . . . . . . . . . 6 | 3.1.2. "status" . . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 3.1.3. "title" . . . . . . . . . . . . . . . . . . . . . . . 7 | 3.1.3. "title" . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 3.1.4. "detail" . . . . . . . . . . . . . . . . . . . . . . 7 | 3.1.4. "detail" . . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 3.1.5. "instance" . . . . . . . . . . . . . . . . . . . . . 7 | 3.1.5. "instance" . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 8 | 3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 8 | |||
| 4. Defining New Problem Types . . . . . . . . . . . . . . . . . 8 | 4. Defining New Problem Types . . . . . . . . . . . . . . . . . 8 | |||
| 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 9 | 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 4.2. Registered Problem Types . . . . . . . . . . . . . . . . 10 | 4.2. Registered Problem Types . . . . . . . . . . . . . . . . 10 | |||
| 4.2.1. about:blank . . . . . . . . . . . . . . . . . . . . . 11 | 4.2.1. about:blank . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 | 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 | |||
| 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 | 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 | |||
| 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
| 7.1. Normative References . . . . . . . . . . . . . . . . . . 12 | 7.1. Normative References . . . . . . . . . . . . . . . . . . 12 | |||
| 7.2. Informative References . . . . . . . . . . . . . . . . . 13 | 7.2. Informative References . . . . . . . . . . . . . . . . . 13 | |||
| Appendix A. JSON Schema for HTTP Problems . . . . . . . . . . . 14 | Appendix A. JSON Schema for HTTP Problems . . . . . . . . . . . 14 | |||
| Appendix B. HTTP Problems and XML . . . . . . . . . . . . . . . 15 | Appendix B. HTTP Problems and XML . . . . . . . . . . . . . . . 15 | |||
| Appendix C. Using Problem Details with Other Formats . . . . . . 17 | Appendix C. Using Problem Details with Other Formats . . . . . . 17 | |||
| Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 18 | Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
| 1. Introduction | 1. Introduction | |||
| HTTP [HTTP] status codes are sometimes not sufficient to convey | HTTP status codes (Section 15 of [HTTP]) cannot always convey enough | |||
| enough information about an error to be helpful. While humans behind | information about errors to be helpful. While humans using Web | |||
| Web browsers can be informed about the nature of the problem with an | browsers can often understand an HTML [HTML5] response body, non- | |||
| HTML [HTML5] response body, non-human consumers of so-called "HTTP | human consumers of HTTP APIs have difficulty doing so. | |||
| APIs" are usually not. | ||||
| This specification defines simple JSON [RFC8259] and XML [XML] | ||||
| document formats to suit this purpose. They are designed to be | ||||
| reused by HTTP APIs, which can identify distinct "problem types" | ||||
| specific to their needs. | ||||
| Thus, API clients can be informed of both the high-level error class | ||||
| (using the status code) and the finer-grained details of the problem | ||||
| (using one of these formats). | ||||
| For example, consider a response that indicates that the client's | To address that shortcoming, this specification defines simple JSON | |||
| account doesn't have enough credit. The 403 Forbidden status code | [RFC8259] and XML [XML] document formats to describe the specifics of | |||
| might be deemed most appropriate to use, as it will inform HTTP- | problem(s) encountered -- "problem details". | |||
| generic software (such as client libraries, caches, and proxies) of | ||||
| the general semantics of the response. | ||||
| However, that doesn't give the API client enough information about | For example, consider a response indicating that the client's account | |||
| why the request was forbidden, the applicable account balance, or how | doesn't have enough credit. The API's designer might decide to use | |||
| to correct the problem. If these details are included in the | the 403 Forbidden status code to inform HTTP-generic software (such | |||
| response body in a machine-readable format, the client can treat it | as client libraries, caches, and proxies) of the response's general | |||
| appropriately; for example, triggering a transfer of more credit into | semantics. API-specific problem details (such as the why the server | |||
| the account. | refused the request and the applicable account balance) can be | |||
| carried in the response content, so that the client can act upon them | ||||
| appropriately (for example, triggering a transfer of more credit into | ||||
| the account). | ||||
| This specification does this by identifying a specific type of | This specification identifies the specific "problem type" (e.g., "out | |||
| problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can | of credit") with a URI [RFC3986]. HTTP APIs can use URIs under their | |||
| do this by nominating new URIs under their control, or by reusing | control to identify problems specific to them, or can reuse existing | |||
| existing ones. | ones to facilitate interoperability and leverage common semantics | |||
| (see Section 4.2). | ||||
| Additionally, problem details can contain other information, such as | Problem details can contain other information, such as a URI | |||
| a URI that identifies the specific occurrence of the problem | identifying the problem's specific occurrence (effectively giving an | |||
| (effectively giving an identifier to the concept "The time Joe didn't | identifier to the concept "The time Joe didn't have enough credit | |||
| have enough credit last Thursday"), which can be useful for support | last Thursday"), which can be useful for support or forensic | |||
| or forensic purposes. | purposes. | |||
| The data model for problem details is a JSON [RFC8259] object; when | The data model for problem details is a JSON [RFC8259] object; when | |||
| formatted as a JSON document, it uses the "application/problem+json" | serialized as a JSON document, it uses the "application/problem+json" | |||
| media type. Appendix B defines how to express them in an equivalent | media type. Appendix B defines an equivalent XML format, which uses | |||
| XML format, which uses the "application/problem+xml" media type. | the "application/problem+xml" media type. | |||
| Note that problem details are (naturally) not the only way to convey | Note that problem details are (naturally) not the only way to convey | |||
| the details of a problem in HTTP; if the response is still a | the details of a problem in HTTP. If the response is still a | |||
| representation of a resource, for example, it's often preferable to | representation of a resource, for example, it's often preferable to | |||
| accommodate describing the relevant details in that application's | describe the relevant details in that application's format. | |||
| format. Likewise, in many situations, there is an appropriate HTTP | Likewise, defined HTTP status codes cover many situations with no | |||
| status code that does not require extra detail to be conveyed. | need to convey extra detail. | |||
| Instead, the aim of this specification is to define common error | This specification's aim is to define common error formats for | |||
| formats for those applications that need one, so that they aren't | applications that need one so that they aren't required to define | |||
| required to define their own, or worse, tempted to redefine the | their own, or worse, tempted to redefine the semantics of existing | |||
| semantics of existing HTTP status codes. Even if an application | HTTP status codes. Even if an application chooses not to use it to | |||
| chooses not to use it to convey errors, reviewing its design can help | convey errors, reviewing its design can help guide the design | |||
| guide the design decisions faced when conveying errors in an existing | decisions faced when conveying errors in an existing format. | |||
| format. | ||||
| 2. Requirements | 2. Requirements | |||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
| "OPTIONAL" in this document are to be interpreted as described in BCP | "OPTIONAL" in this document are to be interpreted as described in BCP | |||
| 14 [RFC2119] [RFC8174] when, and only when, they appear in all | 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |||
| capitals, as shown here. | capitals, as shown here. | |||
| 3. The Problem Details JSON Object | 3. The Problem Details JSON Object | |||
| skipping to change at page 4, line 36 ¶ | skipping to change at page 4, line 28 ¶ | |||
| { | { | |||
| "type": "https://example.com/probs/out-of-credit", | "type": "https://example.com/probs/out-of-credit", | |||
| "title": "You do not have enough credit.", | "title": "You do not have enough credit.", | |||
| "detail": "Your current balance is 30, but that costs 50.", | "detail": "Your current balance is 30, but that costs 50.", | |||
| "instance": "/account/12345/msgs/abc", | "instance": "/account/12345/msgs/abc", | |||
| "balance": 30, | "balance": 30, | |||
| "accounts": ["/account/12345", | "accounts": ["/account/12345", | |||
| "/account/67890"] | "/account/67890"] | |||
| } | } | |||
| Here, the out-of-credit problem (identified by its type URI) | Here, the out-of-credit problem (identified by its type) indicates | |||
| indicates the reason for the 403 in "title", gives a reference for | the reason for the 403 in "title", identifies the specific problem | |||
| the specific problem occurrence with "instance", gives occurrence- | occurrence with "instance", gives occurrence-specific details in | |||
| specific details in "detail", and adds two extensions; "balance" | "detail", and adds two extensions; "balance" conveys the account's | |||
| conveys the account's balance, and "accounts" gives links where the | balance, and "accounts" lists links where the account can be topped | |||
| account can be topped up. | up. | |||
| The ability to convey problem-specific extensions allows more than | When designed to accommodate it, problem-specific extensions can | |||
| one problem to be conveyed. For example: | allow more than one instance of the same problem type to be conveyed. | |||
| For example: | ||||
| HTTP/1.1 400 Bad Request | HTTP/1.1 400 Bad Request | |||
| Content-Type: application/problem+json | Content-Type: application/problem+json | |||
| Content-Language: en | Content-Language: en | |||
| { | { | |||
| "type": "https://example.net/validation-error", | "type": "https://example.net/validation-error", | |||
| "title": "Your request parameters didn't validate.", | "title": "Your request is not valid.", | |||
| "invalid_params": [ { | "causes": [ | |||
| "name": "age", | { | |||
| "reason": "must be a positive integer" | "detail": "must be a positive integer", | |||
| }, | "problem-pointer": "#/age" | |||
| { | }, | |||
| "name": "color", | { | |||
| "reason": "must be 'green', 'red' or 'blue'"} | "detail": "must be 'green', 'red' or 'blue'", | |||
| ] | "problem-pointer": "#/profile/color" | |||
| } | } | |||
| ] | ||||
| } | ||||
| Note that this requires each of the subproblems to be similar enough | The fictional problem type here defines the "causes" extension, an | |||
| to use the same HTTP status code. If they do not, the 207 (Multi- | array that describes the details of multiple occurrences. Each | |||
| Status) code [RFC4918] could be used to encapsulate multiple status | member is an object containing "detail" to describe the issue, and | |||
| messages. | "problem-pointer" to locate the problem within the request's content | |||
| using a JSON Pointer [RFC6901]. | ||||
| When an API encounters multiple problems that do not share the same | ||||
| type, it is RECOMMENDED that the most relevant or urgent problem be | ||||
| represented in the response. While it is possible to create generic | ||||
| "batch" problem types that convey multiple, disparate types, they do | ||||
| not map well into HTTP semantics. | ||||
| 3.1. Members of a Problem Details Object | 3.1. Members of a Problem Details Object | |||
| Problem detail objects can have the following members. If the type | Problem detail objects can have the following members. If a member's | |||
| of a member's value does not match the specified type, the member | value type does not match the specified type, the member MUST be | |||
| MUST be ignored -- i.e., processing will continue as if the member | ignored -- i.e., processing will continue as if the member had not | |||
| had not been present. | been present. | |||
| 3.1.1. "type" | 3.1.1. "type" | |||
| The "type" member is a JSON string containing a URI reference | The "type" member is a JSON string containing a URI reference | |||
| [RFC3986] that identifies the problem type. Consumers MUST use the | [RFC3986] that identifies the problem type. Consumers MUST use the | |||
| "type" URI (after resolution, if necessary) as the primary identifier | "type" URI (after resolution, if necessary) problem's primary | |||
| for the problem type. | identifier. | |||
| When this member is not present, its value is assumed to be | When this member is not present, its value is assumed to be | |||
| "about:blank". | "about:blank". | |||
| If the type URI is a locator (e.g., those with a "http" or "https" | If the type URI is a locator (e.g., those with a "http" or "https" | |||
| scheme), dereferencing it SHOULD provide human-readable documentation | scheme), dereferencing it SHOULD provide human-readable documentation | |||
| for the problem type (e.g., using HTML [HTML5]). However, consumers | for the problem type (e.g., using HTML [HTML5]). However, consumers | |||
| SHOULD NOT automatically dereference the type URI, unless they do so | SHOULD NOT automatically dereference the type URI, unless they do so | |||
| in the course of providing information to developers (e.g., when a | when providing information to developers (e.g., when a debugging tool | |||
| debugging tool is in use). | is in use). | |||
| When "type" contains a relative URI, it is resolved relative to the | When "type" contains a relative URI, it is resolved relative to the | |||
| document's base URI, as per [RFC3986], Section 5. However, using | document's base URI, as per [RFC3986], Section 5. However, using | |||
| relative URIs can cause confusion, and they might not be handled | relative URIs can cause confusion, and they might not be handled | |||
| correctly by all implementations. | correctly by all implementations. | |||
| For example, if the two resources "https://api.example.org/foo/ | For example, if the two resources "https://api.example.org/foo/ | |||
| bar/123" and "https://api.example.org/widget/456" both respond with a | bar/123" and "https://api.example.org/widget/456" both respond with a | |||
| "type" equal to the relative URI reference "example-problem", when | "type" equal to the relative URI reference "example-problem", when | |||
| resolved they will identify different resources | resolved they will identify different resources | |||
| skipping to change at page 6, line 26 ¶ | skipping to change at page 6, line 33 ¶ | |||
| result, it is RECOMMENDED that absolute URIs be used in "type" when | result, it is RECOMMENDED that absolute URIs be used in "type" when | |||
| possible, and that when relative URIs are used, they include the full | possible, and that when relative URIs are used, they include the full | |||
| path (e.g., "/types/123"). | path (e.g., "/types/123"). | |||
| The type URI can also be a non-resolvable URI. For example, the tag | The type URI can also be a non-resolvable URI. For example, the tag | |||
| URI scheme [RFC4151] can be used to uniquely identify problem types: | URI scheme [RFC4151] can be used to uniquely identify problem types: | |||
| tag:mnot@mnot.net,2021-09-17:OutOfLuck | tag:mnot@mnot.net,2021-09-17:OutOfLuck | |||
| Non-resolvable URIs ought not be used when there is some future | Non-resolvable URIs ought not be used when there is some future | |||
| possibility that it might become desireable to do so. For example, | possibility that it might become desirable to do so. For example, if | |||
| if the URI above were used in an API and later a tool was adopted | an API designer used the URI above and later adopted a tool that | |||
| that resolves type URIs to discover information about the error, | resolves type URIs to discover information about the error, taking | |||
| taking advantage of that capability would require switching to a | advantage of that capability would require switching to a resolvable | |||
| resolvable URI, thereby creating a new identity for the problem type | URI, creating a new identity for the problem type and thus | |||
| and thus introducing a breaking change. | introducing a breaking change. | |||
| 3.1.2. "status" | 3.1.2. "status" | |||
| The "status" member is a JSON number indicating the HTTP status code | The "status" member is a JSON number indicating the HTTP status code | |||
| ([HTTP], Section 15) generated by the origin server for this | ([HTTP], Section 15) generated by the origin server for this | |||
| occurrence of the problem. | occurrence of the problem. | |||
| The "status" member, if present, is only advisory; it conveys the | The "status" member, if present, is only advisory; it conveys the | |||
| HTTP status code used for the convenience of the consumer. | HTTP status code used for the convenience of the consumer. | |||
| Generators MUST use the same status code in the actual HTTP response, | Generators MUST use the same status code in the actual HTTP response, | |||
| skipping to change at page 7, line 11 ¶ | skipping to change at page 7, line 17 ¶ | |||
| changed (e.g., by an intermediary or cache), and when message bodies | changed (e.g., by an intermediary or cache), and when message bodies | |||
| persist without HTTP information. Generic HTTP software will still | persist without HTTP information. Generic HTTP software will still | |||
| use the HTTP status code. | use the HTTP status code. | |||
| 3.1.3. "title" | 3.1.3. "title" | |||
| The "title" member is a JSON string containing a short, human- | The "title" member is a JSON string containing a short, human- | |||
| readable summary of the problem type. | readable summary of the problem type. | |||
| It SHOULD NOT change from occurrence to occurrence of the problem, | It SHOULD NOT change from occurrence to occurrence of the problem, | |||
| except for purposes of localization (e.g., using proactive content | except for localization (e.g., using proactive content negotiation; | |||
| negotiation; see [HTTP], Section 12.1). | see [HTTP], Section 12.1). | |||
| The "title" string is advisory and included only for users who are | The "title" string is advisory and included only for users who are | |||
| not aware of the semantics of the URI and do not have the ability to | not aware of the semantics of the URI and can not discover them | |||
| discover them (e.g., offline log analysis). | (e.g., during offline log analysis). | |||
| 3.1.4. "detail" | 3.1.4. "detail" | |||
| The "detail" member is a JSON string containing a human-readable | The "detail" member is a JSON string containing a human-readable | |||
| explanation specific to this occurrence of the problem. | explanation specific to this occurrence of the problem. | |||
| The "detail" member, if present, ought to focus on helping the client | The "detail" member, if present, ought to focus on helping the client | |||
| correct the problem, rather than giving debugging information. | correct the problem, rather than giving debugging information. | |||
| Consumers SHOULD NOT parse the "detail" member for information; | Consumers SHOULD NOT parse the "detail" member for information; | |||
| skipping to change at page 8, line 19 ¶ | skipping to change at page 8, line 29 ¶ | |||
| 3.2. Extension Members | 3.2. Extension Members | |||
| Problem type definitions MAY extend the problem details object with | Problem type definitions MAY extend the problem details object with | |||
| additional members. | additional members. | |||
| For example, our "out of credit" problem above defines two such | For example, our "out of credit" problem above defines two such | |||
| extensions -- "balance" and "accounts" to convey additional, problem- | extensions -- "balance" and "accounts" to convey additional, problem- | |||
| specific information. | specific information. | |||
| Similarly, the "Multi-Status" example defines two extensions -- | ||||
| "causes" and "problem-pointer". Extensions like "problem-pointer" | ||||
| are more appropriate to use for problems associated with client side | ||||
| errors 4xx only. | ||||
| Clients consuming problem details MUST ignore any such extensions | Clients consuming problem details MUST ignore any such extensions | |||
| that they don't recognize; this allows problem types to evolve and | that they don't recognize; this allows problem types to evolve and | |||
| include additional information in the future. | include additional information in the future. | |||
| Note that because extensions are effectively put into a namespace by | Note that because extensions are effectively put into a namespace by | |||
| the problem type, it is not possible to define new "standard" members | the problem type, it is not possible to define new "standard" members | |||
| without defining a new media type. | without defining a new media type. | |||
| 4. Defining New Problem Types | 4. Defining New Problem Types | |||
| skipping to change at page 8, line 43 ¶ | skipping to change at page 9, line 12 ¶ | |||
| Before doing so, it's important to understand what they are good for, | Before doing so, it's important to understand what they are good for, | |||
| and what's better left to other mechanisms. | and what's better left to other mechanisms. | |||
| Problem details are not a debugging tool for the underlying | Problem details are not a debugging tool for the underlying | |||
| implementation; rather, they are a way to expose greater detail about | implementation; rather, they are a way to expose greater detail about | |||
| the HTTP interface itself. Designers of new problem types need to | the HTTP interface itself. Designers of new problem types need to | |||
| carefully consider the Security Considerations (Section 5), in | carefully consider the Security Considerations (Section 5), in | |||
| particular, the risk of exposing attack vectors by exposing | particular, the risk of exposing attack vectors by exposing | |||
| implementation internals through error messages. | implementation internals through error messages. | |||
| Likewise, truly generic problems -- i.e., conditions that could | Likewise, truly generic problems -- i.e., conditions that might apply | |||
| potentially apply to any resource on the Web -- are usually better | to any resource on the Web -- are usually better expressed as plain | |||
| expressed as plain status codes. For example, a "write access | status codes. For example, a "write access disallowed" problem is | |||
| disallowed" problem is probably unnecessary, since a 403 Forbidden | probably unnecessary, since a 403 Forbidden status code in response | |||
| status code in response to a PUT request is self-explanatory. | to a PUT request is self-explanatory. | |||
| Finally, an application might have a more appropriate way to carry an | Finally, an application might have a more appropriate way to carry an | |||
| error in a format that it already defines. Problem details are | error in a format that it already defines. Problem details are | |||
| intended to avoid the necessity of establishing new "fault" or | intended to avoid the necessity of establishing new "fault" or | |||
| "error" document formats, not to replace existing domain-specific | "error" document formats, not to replace existing domain-specific | |||
| formats. | formats. | |||
| That said, it is possible to add support for problem details to | That said, it is possible to add support for problem details to | |||
| existing HTTP APIs using HTTP content negotiation (e.g., using the | existing HTTP APIs using HTTP content negotiation (e.g., using the | |||
| Accept request header to indicate a preference for this format; see | Accept request header to indicate a preference for this format; see | |||
| skipping to change at page 9, line 33 ¶ | skipping to change at page 9, line 46 ¶ | |||
| Problem type definitions MAY specify the use of the Retry-After | Problem type definitions MAY specify the use of the Retry-After | |||
| response header ([HTTP], Section 10.2.3) in appropriate | response header ([HTTP], Section 10.2.3) in appropriate | |||
| circumstances. | circumstances. | |||
| A problem's type URI SHOULD resolve to HTML [HTML5] documentation | A problem's type URI SHOULD resolve to HTML [HTML5] documentation | |||
| that explains how to resolve the problem. | that explains how to resolve the problem. | |||
| A problem type definition MAY specify additional members on the | A problem type definition MAY specify additional members on the | |||
| problem details object. For example, an extension might use typed | problem details object. For example, an extension might use typed | |||
| links [RFC8288] to another resource that can be used by machines to | links [RFC8288] to another resource that machines can use to resolve | |||
| resolve the problem. | the problem. | |||
| If such additional members are defined, their names SHOULD start with | If such additional members are defined, their names SHOULD start with | |||
| a letter (ALPHA, as per [RFC5234], Appendix B.1) and SHOULD consist | a letter (ALPHA, as per [RFC5234], Appendix B.1) and SHOULD comprise | |||
| of characters from ALPHA, DIGIT ([RFC5234], Appendix B.1), and "_" | characters from ALPHA, DIGIT ([RFC5234], Appendix B.1), and "_" (so | |||
| (so that it can be serialized in formats other than JSON), and they | that it can be serialized in formats other than JSON), and they | |||
| SHOULD be three characters or longer. | SHOULD be three characters or longer. | |||
| 4.1. Example | 4.1. Example | |||
| For example, if you are publishing an HTTP API to your online | For example, if you are publishing an HTTP API to your online | |||
| shopping cart, you might need to indicate that the user is out of | shopping cart, you might need to indicate that the user is out of | |||
| credit (our example from above), and therefore cannot make the | credit (our example from above), and therefore cannot make the | |||
| purchase. | purchase. | |||
| If you already have an application-specific format that can | If you already have an application-specific format that can | |||
| accommodate this information, it's probably best to do that. | accommodate this information, it's probably best to do that. | |||
| However, if you don't, you might consider using one of the problem | However, if you don't, you might use one of the problem details | |||
| details formats -- JSON if your API is JSON-based, or XML if it uses | formats -- JSON if your API is JSON-based, or XML if it uses that | |||
| that format. | format. | |||
| To do so, you might look for an already-defined type URI that suits | To do so, you might look in the registry (Section 4.2) for an | |||
| your purposes. If one is available, you can reuse that URI. | already-defined type URI that suits your purposes. If one is | |||
| available, you can reuse that URI. | ||||
| If one isn't available, you could mint and document a new type URI | If one isn't available, you could mint and document a new type URI | |||
| (which ought to be under your control and stable over time), an | (which ought to be under your control and stable over time), an | |||
| appropriate title and the HTTP status code that it will be used with, | appropriate title and the HTTP status code that it will be used with, | |||
| along with what it means and how it should be handled. | along with what it means and how it should be handled. | |||
| In summary: an instance URI will always identify a specific | ||||
| occurrence of a problem. On the other hand, type URIs can be reused | ||||
| if an appropriate description of a problem type is already available | ||||
| someplace else, or they can be created for new problem types. | ||||
| 4.2. Registered Problem Types | 4.2. Registered Problem Types | |||
| This specification defines the HTTP Problem Type registry for common, | This specification defines the HTTP Problem Type registry for common, | |||
| widely-used problem type URIs, to promote reuse. | widely-used problem type URIs, to promote reuse. | |||
| Registration requests are reviewed and approved by a Designated | The policy for this registry is Specification Required, per | |||
| Expert, as per [RFC8126], Section 4.5. A specification document is | [RFC8126], Section 4.5. | |||
| appreciated, but not required. | ||||
| When evaluating requests the Expert(s) should consider community | When evaluating requests, the Expert(s) should consider community | |||
| feedback, how well-defined the problem type is, and this | feedback, how well-defined the problem type is, and this | |||
| specification's requirements. Vendor-specific, application-specific, | specification's requirements. Vendor-specific, application-specific, | |||
| and deployment-specific values are not registrable. | and deployment-specific values are not registrable. Specification | |||
| documents should be published in a stable, freely available manner | ||||
| (ideally located with a URL), but need not be standards. | ||||
| Registrations MAY use the prefix "https://iana.org/assignments/http- | Registrations MAY use the prefix "https://iana.org/assignments/http- | |||
| problem-types#", and are encouraged to do so when a stable, neutral | problem-types#" for the type URI. | |||
| URI is desirable. | ||||
| Registration requests should use the following template: | Registration requests should use the following template: | |||
| * Type URI: [a URI for the problem type] | * Type URI: [a URI for the problem type] | |||
| * Title: [a short description of the problem type] | * Title: [a short description of the problem type] | |||
| * Recommended HTTP status code: [what status code is most | * Recommended HTTP status code: [what status code is most | |||
| appropriate to use with the type] | appropriate to use with the type] | |||
| skipping to change at page 12, line 6 ¶ | skipping to change at page 12, line 15 ¶ | |||
| Risks include leaking information that can be exploited to compromise | Risks include leaking information that can be exploited to compromise | |||
| the system, access to the system, or the privacy of users of the | the system, access to the system, or the privacy of users of the | |||
| system. | system. | |||
| Generators providing links to occurrence information are encouraged | Generators providing links to occurrence information are encouraged | |||
| to avoid making implementation details such as a stack dump available | to avoid making implementation details such as a stack dump available | |||
| through the HTTP interface, since this can expose sensitive details | through the HTTP interface, since this can expose sensitive details | |||
| of the server implementation, its data, and so on. | of the server implementation, its data, and so on. | |||
| The "status" member duplicates the information available in the HTTP | The "status" member duplicates the information available in the HTTP | |||
| status code itself, thereby bringing the possibility of disagreement | status code itself, bringing the possibility of disagreement between | |||
| between the two. Their relative precedence is not clear, since a | the two. Their relative precedence is not clear, since a | |||
| disagreement might indicate that (for example) an intermediary has | disagreement might indicate that (for example) an intermediary has | |||
| modified the HTTP status code in transit (e.g., by a proxy or cache). | changed the HTTP status code in transit (e.g., by a proxy or cache). | |||
| Generic HTTP software (such as proxies, load balancers, firewalls, | ||||
| As such, those defining problem types as well as generators and | and virus scanners) are unlikely to know of or respect the status | |||
| consumers of problems need to be aware that generic software (such as | code conveyed in this member. | |||
| proxies, load balancers, firewalls, and virus scanners) are unlikely | ||||
| to know of or respect the status code conveyed in this member. | ||||
| 6. IANA Considerations | 6. IANA Considerations | |||
| Please update the "application/problem+json" and "application/ | Please update the "application/problem+json" and "application/ | |||
| problem+xml" registrations in the Internet media types registry | problem+xml" registrations in the Internet media types registry | |||
| [RFC6838]. to refer to this document. | [RFC6838]. to refer to this document. | |||
| Please create the HTTP Problem Types Registry, as specified in | Please create the HTTP Problem Types Registry, as specified in | |||
| Section 4.2, and populate it with "about:blank" as per Section 4.2.1. | Section 4.2, and populate it with "about:blank" as per Section 4.2.1. | |||
| skipping to change at page 14, line 19 ¶ | skipping to change at page 14, line 23 ¶ | |||
| [RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694, | [RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694, | |||
| DOI 10.17487/RFC6694, August 2012, | DOI 10.17487/RFC6694, August 2012, | |||
| <https://www.rfc-editor.org/rfc/rfc6694>. | <https://www.rfc-editor.org/rfc/rfc6694>. | |||
| [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type | [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type | |||
| Specifications and Registration Procedures", BCP 13, | Specifications and Registration Procedures", BCP 13, | |||
| RFC 6838, DOI 10.17487/RFC6838, January 2013, | RFC 6838, DOI 10.17487/RFC6838, January 2013, | |||
| <https://www.rfc-editor.org/rfc/rfc6838>. | <https://www.rfc-editor.org/rfc/rfc6838>. | |||
| [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., | ||||
| "JavaScript Object Notation (JSON) Pointer", RFC 6901, | ||||
| DOI 10.17487/RFC6901, April 2013, | ||||
| <https://www.rfc-editor.org/rfc/rfc6901>. | ||||
| [RFC8288] Nottingham, M., "Web Linking", RFC 8288, | [RFC8288] Nottingham, M., "Web Linking", RFC 8288, | |||
| DOI 10.17487/RFC8288, October 2017, | DOI 10.17487/RFC8288, October 2017, | |||
| <https://www.rfc-editor.org/rfc/rfc8288>. | <https://www.rfc-editor.org/rfc/rfc8288>. | |||
| [XSLT] Clark, J., Pieters, S., and H. Thompson, "Associating | [XSLT] Clark, J., Pieters, S., and H. Thompson, "Associating | |||
| Style Sheets with XML documents 1.0 (Second Edition)", | Style Sheets with XML documents 1.0 (Second Edition)", | |||
| World Wide Web Consortium Recommendation REC-xml- | World Wide Web Consortium Recommendation REC-xml- | |||
| stylesheet-20101028, 28 October 2010, | stylesheet-20101028, 28 October 2010, | |||
| <https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028>. | <https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028>. | |||
| skipping to change at page 15, line 48 ¶ | skipping to change at page 15, line 48 ¶ | |||
| "format": "uri-reference", | "format": "uri-reference", | |||
| "description": "A URI reference that identifies the \ | "description": "A URI reference that identifies the \ | |||
| specific occurrence of the problem. It may or may not yield \ | specific occurrence of the problem. It may or may not yield \ | |||
| further information if dereferenced." | further information if dereferenced." | |||
| } | } | |||
| } | } | |||
| } | } | |||
| Appendix B. HTTP Problems and XML | Appendix B. HTTP Problems and XML | |||
| Some HTTP-based APIs use XML [XML] as their primary format | HTTP-based APIs that use XML [XML] can express problem details using | |||
| convention. Such APIs can express problem details using the format | the format defined in this appendix. | |||
| defined in this appendix. | ||||
| The RELAX NG schema [ISO-19757-2] for the XML format is as follows. | The RELAX NG schema [ISO-19757-2] for the XML format is: | |||
| Keep in mind that this schema is only meant as documentation, and not | ||||
| as a normative schema that captures all constraints of the XML | ||||
| format. Also, it would be possible to use other XML schema languages | ||||
| to define a similar set of constraints (depending on the features of | ||||
| the chosen schema language). | ||||
| default namespace ns = "urn:ietf:rfc:7807" | default namespace ns = "urn:ietf:rfc:7807" | |||
| start = problem | start = problem | |||
| problem = | problem = | |||
| element problem { | element problem { | |||
| ( element type { xsd:anyURI }? | ( element type { xsd:anyURI }? | |||
| & element title { xsd:string }? | & element title { xsd:string }? | |||
| & element detail { xsd:string }? | & element detail { xsd:string }? | |||
| & element status { xsd:positiveInteger }? | & element status { xsd:positiveInteger }? | |||
| & element instance { xsd:anyURI }? ), | & element instance { xsd:anyURI }? ), | |||
| anyNsElement | anyNsElement | |||
| } | } | |||
| anyNsElement = | anyNsElement = | |||
| ( element ns:* { anyNsElement | text } | ( element ns:* { anyNsElement | text } | |||
| | attribute * { text })* | | attribute * { text })* | |||
| Note that this schema is only intended as documentation, and not as a | ||||
| normative schema that captures all constraints of the XML format. It | ||||
| is possible to use other XML schema languages to define a similar set | ||||
| of constraints (depending on the features of the chosen schema | ||||
| language). | ||||
| The media type for this format is "application/problem+xml". | The media type for this format is "application/problem+xml". | |||
| Extension arrays and objects are serialized into the XML format by | Extension arrays and objects are serialized into the XML format by | |||
| considering an element containing a child or children to represent an | considering an element containing a child or children to represent an | |||
| object, except for elements that contain only child element(s) named | object, except for elements that contain only child element(s) named | |||
| 'i', which are considered arrays. For example, the example above | 'i', which are considered arrays. For example, the example above | |||
| appears in XML as follows: | appears in XML as follows: | |||
| HTTP/1.1 403 Forbidden | HTTP/1.1 403 Forbidden | |||
| Content-Type: application/problem+xml | Content-Type: application/problem+xml | |||
| skipping to change at page 17, line 21 ¶ | skipping to change at page 17, line 4 ¶ | |||
| <type>https://example.com/probs/out-of-credit</type> | <type>https://example.com/probs/out-of-credit</type> | |||
| <title>You do not have enough credit.</title> | <title>You do not have enough credit.</title> | |||
| <detail>Your current balance is 30, but that costs 50.</detail> | <detail>Your current balance is 30, but that costs 50.</detail> | |||
| <instance>https://example.net/account/12345/msgs/abc</instance> | <instance>https://example.net/account/12345/msgs/abc</instance> | |||
| <balance>30</balance> | <balance>30</balance> | |||
| <accounts> | <accounts> | |||
| <i>https://example.net/account/12345</i> | <i>https://example.net/account/12345</i> | |||
| <i>https://example.net/account/67890</i> | <i>https://example.net/account/67890</i> | |||
| </accounts> | </accounts> | |||
| </problem> | </problem> | |||
| This format uses an XML namespace, primarily to allow embedding it | ||||
| Note that this format uses an XML namespace. This is primarily to | into other XML-based formats; it does not imply that it can or should | |||
| allow embedding it into other XML-based formats; it does not imply | be extended with elements or attributes in other namespaces. The | |||
| that it can or should be extended with elements or attributes in | RELAX NG schema explicitly only allows elements from the one | |||
| other namespaces. The RELAX NG schema explicitly only allows | namespace used in the XML format. Any extension arrays and objects | |||
| elements from the one namespace used in the XML format. Any | MUST be serialized into XML markup using only that namespace. | |||
| extension arrays and objects MUST be serialized into XML markup using | ||||
| only that namespace. | ||||
| When using the XML format, it is possible to embed an XML processing | When using the XML format, it is possible to embed an XML processing | |||
| instruction in the XML that instructs clients to transform the XML, | instruction in the XML that instructs clients to transform the XML, | |||
| using the referenced XSLT code [XSLT]. If this code is transforming | using the referenced XSLT code [XSLT]. If this code is transforming | |||
| the XML into (X)HTML, then it is possible to serve the XML format, | the XML into (X)HTML, then it is possible to serve the XML format, | |||
| and yet have clients capable of performing the transformation display | and yet have clients capable of performing the transformation display | |||
| human-friendly (X)HTML that is rendered and displayed at the client. | human-friendly (X)HTML that is rendered and displayed at the client. | |||
| Note that when using this method, it is advisable to use XSLT 1.0 in | Note that when using this method, it is advisable to use XSLT 1.0 in | |||
| order to maximize the number of clients capable of executing the XSLT | order to maximize the number of clients capable of executing the XSLT | |||
| code. | code. | |||
| skipping to change at page 18, line 38 ¶ | skipping to change at page 18, line 21 ¶ | |||
| The authors would like to thank Jan Algermissen, Subbu Allamaraju, | The authors would like to thank Jan Algermissen, Subbu Allamaraju, | |||
| Mike Amundsen, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, | Mike Amundsen, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, | |||
| Julian Reschke, and James Snell for review of this specification. | Julian Reschke, and James Snell for review of this specification. | |||
| Authors' Addresses | Authors' Addresses | |||
| Mark Nottingham | Mark Nottingham | |||
| Prahran | Prahran | |||
| Australia | Australia | |||
| Email: mnot@mnot.net | Email: mnot@mnot.net | |||
| URI: https://www.mnot.net/ | URI: https://www.mnot.net/ | |||
| Erik Wilde | Erik Wilde | |||
| Email: erik.wilde@dret.net | Email: erik.wilde@dret.net | |||
| URI: http://dret.net/netdret/ | URI: http://dret.net/netdret/ | |||
| Sanjay Dalal | Sanjay Dalal | |||
| United States of America | ||||
| Email: sanjay.dalal@cal.berkeley.edu | Email: sanjay.dalal@cal.berkeley.edu | |||
| URI: https://github.com/sdatspun2 | URI: https://github.com/sdatspun2 | |||
| End of changes. 48 change blocks. | ||||
| 157 lines changed or deleted | 158 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||