Problem Details for HTTP APIs
RFC 7807
|
| Document |
Type |
|
RFC - Proposed Standard
(March 2016; No errata)
|
|
Last updated |
|
2016-03-31
|
|
Replaces |
|
draft-nottingham-http-problem
|
|
Stream |
|
IETF
|
|
Formats |
|
plain text
pdf
html
bibtex
|
| Stream |
WG state
|
|
Submitted to IESG for Publication
Dec 2015
|
|
Document shepherd |
|
Murray Kucherawy
|
|
Shepherd write-up |
|
Show
(last changed 2015-11-20)
|
| IESG |
IESG state |
|
RFC 7807 (Proposed Standard)
|
|
Consensus Boilerplate |
|
Yes
|
|
Telechat date |
|
|
|
Responsible AD |
|
Barry Leiba
|
|
Send notices to |
|
"Murray Kucherawy" <superuser@gmail.com>
|
| IANA |
IANA review state |
|
Version Changed - Review Needed
|
|
IANA action state |
|
RFC-Ed-Ack
|
Internet Engineering Task Force (IETF) M. Nottingham
Request for Comments: 7807 Akamai
Category: Standards Track E. Wilde
ISSN: 2070-1721 March 2016
Problem Details for HTTP APIs
Abstract
This document defines a "problem detail" as a way to carry machine-
readable details of errors in a HTTP response to avoid the need to
define new error response formats for HTTP APIs.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7807.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Nottingham & Wilde Standards Track [Page 1]
RFC 7807 Problem Details March 2016
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3
3. The Problem Details JSON Object . . . . . . . . . . . . . . . 3
3.1. Members of a Problem Details Object . . . . . . . . . . . 5
3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6
4. Defining New Problem Types . . . . . . . . . . . . . . . . . 6
4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2. Predefined Problem Types . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6.1. application/problem+json . . . . . . . . . . . . . . . . 9
6.2. application/problem+xml . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
7.1. Normative References . . . . . . . . . . . . . . . . . . 11
7.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 14
Appendix B. Using Problem Details with Other Formats . . . . . . 15
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction
HTTP [RFC7230] status codes are sometimes not sufficient to convey
enough information about an error to be helpful. While humans behind
Web browsers can be informed about the nature of the problem with an
HTML [W3C.REC-html5-20141028] response body, non-human consumers of
so-called "HTTP APIs" are usually not.
This specification defines simple JSON [RFC7159] and XML
[W3C.REC-xml-20081126] 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
account doesn't have enough credit. The 403 Forbidden status code
might be deemed most appropriate to use, as it will inform HTTP-
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
why the request was forbidden, the applicable account balance, or how
to correct the problem. If these details are included in the
Nottingham & Wilde Standards Track [Page 2]
Show full document text