Concise Problem Details For CoAP APIs
draft-ietf-core-problem-details-02
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 9290.
|
|
|---|---|---|---|
| Authors | Thomas Fossati , Carsten Bormann | ||
| Last updated | 2022-04-27 | ||
| Replaces | draft-fossati-core-coap-problem | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews |
ARTART Last Call review
(of
-05)
by Harald Alvestrand
On the Right Track
I18NDIR Last Call review
(of
-05)
by Harald Alvestrand
On the Right Track
|
||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Document shepherd | (None) | ||
| IESG | IESG state | Became RFC 9290 (Proposed Standard) | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-core-problem-details-02
CoRE Working Group T. Fossati
Internet-Draft arm
Intended status: Standards Track C. Bormann
Expires: 29 October 2022 Universität Bremen TZI
27 April 2022
Concise Problem Details For CoAP APIs
draft-ietf-core-problem-details-02
Abstract
This document defines a "problem detail" as a way to carry machine-
readable details of errors in a REST response to avoid the need to
define new error response formats for REST APIs. The format is
inspired by, but intended to be more concise than, the Problem
Details for HTTP APIs defined in RFC 7807.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 29 October 2022.
Copyright Notice
Copyright (c) 2022 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 (https://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 Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Fossati & Bormann Expires 29 October 2022 [Page 1]
Internet-Draft CoRE Problem Details April 2022
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. Basic Problem Details . . . . . . . . . . . . . . . . . . . . 3
3. Additional Problem Details . . . . . . . . . . . . . . . . . 4
3.1. Additional Problem Types . . . . . . . . . . . . . . . . 5
3.2. Custom Problem Detail Entries . . . . . . . . . . . . . . 5
3.3. Standard Problem Detail Entries . . . . . . . . . . . . . 5
4. Security Considerations . . . . . . . . . . . . . . . . . . . 6
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
5.1. CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 6
5.2. Standard Problem Detail Key registry . . . . . . . . . . 7
5.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 8
5.4. Content-Format . . . . . . . . . . . . . . . . . . . . . 8
6. Normative References . . . . . . . . . . . . . . . . . . . . 9
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10
1. Introduction
REST response status information such as CoAP [RFC7252] response
codes is sometimes not sufficient to convey enough information about
an error to be helpful. This specification defines a simple and
extensible framework to define CBOR tags to suit this purpose. It is
designed to be reused by REST 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 response code)
and the finer-grained details of the problem (using this vocabulary),
as shown in Figure 1.
+--------+ +--------+
| CoAP | | CoAP |
| Client | | Server |
+----+---+ +----+---+
| |
| Request |
|------------------> |
| |
| <----------------- |
| Error Response |
| with a CBOR Data |
| Item giving |
| Problem Details |
| |
Figure 1: Problem Details: Example with CoAP
Fossati & Bormann Expires 29 October 2022 [Page 2]
Internet-Draft CoRE Problem Details April 2022
The framework presented is largely inspired by the Problem Details
for HTTP APIs defined in [RFC7807].
1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
2. Basic Problem Details
A Concise Problem Details data item is a CBOR data item with the
following structure (notated in CDDL [RFC8610], using 65535 in place
of a tag number to be defined for the type of problem details):
problem-details = #6.65535(problem-details-map)
problem-details-map = non-empty<{
? &(title: -1) => text
? &(detail: -2) => text
? &(instance: -3) => ~uri
standard-problem-detail-entries
custom-problem-detail-entries
}>
standard-problem-detail-entries = (
* nint => any
)
custom-problem-detail-entries = (
* (uint/detail-label) => any
)
detail-label = text .regexp "[^:]+" / ~uri
non-empty<M> = (M) .and ({ + any => any })
Figure 2: Problem Detail Data Item
Due to a limitation of the CDDL notation for tags, the problem type
cannot be expressed under this name in CDDL. It is represented in
the tag number, which is shown here as 65535.
One tag has been registered as a generic problem type by this
specification (see Section 5.1). Further problem types can be
defined by registering additional tags (see Section 3).
A number of problem detail entries, the Standard Problem Detail
entries, are predefined (more predefined details can be registered,
see Section 3.3):
Fossati & Bormann Expires 29 October 2022 [Page 3]
Internet-Draft CoRE Problem Details April 2022
The title (key -1):
A short, human-readable summary of the problem type. It SHOULD
NOT change from occurrence to occurrence of the problem.
The detail (key -2):
A human-readable explanation specific to this occurrence of the
problem.
The instance (key -3):
A URI reference that identifies the specific occurrence of the
problem. It may or may not yield further information if
dereferenced.
Consumers MUST use the type (tag number) as primary identifiers for
the problem type; the "title" string is advisory and included only
for consumers who are not aware of the semantics of the CBOR tag
number used to indicate the specific problem type.
The "detail" member, if present, ought to focus on helping the client
correct the problem, rather than giving debugging information.
Consumers SHOULD NOT parse the "detail" member for information;
extensions (see Section 3) are more suitable and less error-prone
ways to obtain such information.
Note that the "instance" URI reference may be relative; this means
that it must be resolved relative to the document's base URI, as per
[STD66].
Note that the response code information that may be available
together with a problem report is _not_ replicated into a problem
detail entry; compare this with "status" in [RFC7807].
| (*Issue*: Do we still want to define a SPDK for status, so
| implementations can easily stash away the response code
| available from context into the problem details?)
3. Additional Problem Details
This specification defines a single problem type, the Generic Problem
Details problem type (represented by CBOR tag TBD400, Section 5.1).
Fossati & Bormann Expires 29 October 2022 [Page 4]
Internet-Draft CoRE Problem Details April 2022
3.1. Additional Problem Types
To establish a new problem type, different from the Generic Problem
Details problem type, a CBOR Tag number needs to be registered in the
CBOR Tags of [IANA.cbor-tags]. Note that this registry allows the
registration of new tags under the First Come First Served policy
[RFC8126], making new registrations available in a simple interaction
(e.g., via web or email) with IANA, after having filled in the small
template provided in Section 9.2 of [STD94]. Such a registration
SHOULD provide a documentation reference and also SHOULD reference
the present specification.
3.2. Custom Problem Detail Entries
Problem type definitions MAY extend the Problem Details document with
additional entries to convey additional, problem-type-specific
information, _custom problem details_. In the definition of a problem
type, each custom problem detail receives a map key specific to this
problem type (custom problem detail entry map key, unsigned integer
or text); this SHOULD be described in the documentation that goes
along with the registration of a CBOR Tag for the problem type.
For text detail-labels, a name without an embedded colon can be
chosen instead of an integer custom label, or a detail-label that is
a URI. This URI is for identification purposes only and MUST NOT be
dereferenced in the normal course of handling problem details (i.e.,
outside diagnostic/debugging procedures involving humans).
In summary, the keys for Custom Problem Detail entries are in a
namespace specific to the Problem Type the documentation of which
defines these entries. Consumers of a Problem Type instance MUST
ignore any Custom Problem Detail entries that they do not recognize;
this allows problem types to evolve and include additional
information in the future. If, in the evolution of a problem type, a
new problem detail is added that needs to be understood by all
consumers, a new problem type needs to be defined (i.e., problem
detail entries are always elective, never critical, in the
terminology of Section 5.4.1 of [RFC7252]).
3.3. Standard Problem Detail Entries
Beyond the Standard Problem Detail keys defined in Figure 2,
additional Standard Problem Detail keys can be registered (see
Section 5.2). Standard Problem Detail keys are not specific to a
particular problem type; they are intended to be used for problem
details that cover an area of application that includes multiple
registered problem types.
Fossati & Bormann Expires 29 October 2022 [Page 5]
Internet-Draft CoRE Problem Details April 2022
Standard Problem Detail keys are negative integers, so they never can
conflict with Custom Problem Detail keys defined for a problem type
(which are unsigned integers or text strings).
In summary, the keys for Standard Problem Detail entries are in a
global namespace that applies to all Problem Types. The
documentation of a Problem Type MAY provide additional guidance on
how a Standard Problem Detail entry applies to this Problem Type, but
cannot redefine its generic semantics.
Therefore, clients consuming problem details may be able to consume
unknown Problem types (i.e., with unknown CBOR Tag numbers), if the
general context (e.g., a media type known from the context such as
that defined in Section 5.3) indicates that the present specification
is used. Such consumers MUST ignore any Standard Problem Detail
entries that they do not recognize (which, for an unknown tag, by
definition also applies to all Custom Problem Details entries).
4. Security Considerations
The security and privacy considerations outlined in Section 5 of
[RFC7807] apply in full.
5. IANA Considerations
// RFC Editor: please replace RFC XXXX with this RFC number and
// remove this note.
5.1. CBOR Tag
As per [STD94], IANA has created a "CBOR Tags" registry
[IANA.cbor-tags], which serves as the registry for problem details
types (see Section 3). For use as a predefined, generic problem
details type, IANA is requested to allocate the tag defined in
Table 1.
+========+===========+=========================+===========+
| Tag | Data Item | Semantics | Reference |
+========+===========+=========================+===========+
| TBD400 | map | Generic Problem Details | RFCXXXX |
+--------+-----------+-------------------------+-----------+
Table 1: Generic Problem Details tag
Fossati & Bormann Expires 29 October 2022 [Page 6]
Internet-Draft CoRE Problem Details April 2022
5.2. Standard Problem Detail Key registry
This specification defines a new sub-registry for Standard Problem
Detail Keys in the CoRE Parameters registry [IANA.core-parameters],
with the policy "specification required" [RFC8126].
Each entry in the registry must include:
key value:
a negative integer to be used as the value of the key
name:
a name that could be used in implementations for the key
type:
type of the data associated with the key; preferably in CDDL
notation
brief description:
a brief description
reference:
a reference document
Initial entries in this sub-registry are as follows:
+=======+==========+======+=============================+===========+
| Key | Name | Type | Brief Description | Reference |
| value | | | | |
+=======+==========+======+=============================+===========+
| -1 | title | text | short, human-readable | RFCXXXX |
| | | | summary of the problem | |
| | | | type | |
+-------+----------+------+-----------------------------+-----------+
| -2 | detail | text | human-readable explanation | RFCXXXX |
| | | | specific to this | |
| | | | occurrence of the problem | |
+-------+----------+------+-----------------------------+-----------+
| -3 | instance | ~uri | URI reference identifying | RFCXXXX |
| | | | specific occurrence of the | |
| | | | problem | |
+-------+----------+------+-----------------------------+-----------+
Table 2: Initial Entries in Standard Problem Detail Key registry
Fossati & Bormann Expires 29 October 2022 [Page 7]
Internet-Draft CoRE Problem Details April 2022
5.3. Media Type
IANA is requested to add the following Media-Type to the "Media
Types" registry [IANA.media-types].
+============================+============================+=========+
|Name |Template |Reference|
+============================+============================+=========+
|concise-problem-details+cbor|application/concise-problem-|RFCXXXX, |
| |details+cbor |Section |
| | |5.3 |
+----------------------------+----------------------------+---------+
Table 3: New Media Type application/concise-problem-details+cbor
Type name: application
Subtype name: concise-problem-details+cbor
Required parameters: none
Optional parameters: none
Encoding considerations: binary (CBOR data item)
Security considerations: Section 4 of RFC XXXX
Interoperability considerations: none
Published specification: Section 5.3 of RFC XXXX
Applications that use this media type: Clients and servers in the
Internet of Things
Fragment identifier considerations: The syntax and semantics of
fragment identifiers is as specified for "application/cbor". (At
publication of RFC XXXX, there is no fragment identification
syntax defined for "application/cbor".)
Person & email address to contact for further information: CoRE WG
mailing list (core@ietf.org), or IETF Applications and Real-Time
Area (art@ietf.org)
Intended usage: COMMON
Restrictions on usage: none
Author/Change controller: IETF
Provisional registration: no
5.4. Content-Format
IANA is requested to register a Content-Format number in the "CoAP
Content-Formats" sub-registry, within the "Constrained RESTful
Environments (CoRE) Parameters" Registry [IANA.core-parameters], as
follows:
Fossati & Bormann Expires 29 October 2022 [Page 8]
Internet-Draft CoRE Problem Details April 2022
+==============================+================+======+===========+
| Content-Type | Content Coding | ID | Reference |
+==============================+================+======+===========+
| application/concise-problem- | - | TBD1 | RFC XXXX |
| details+cbor | | | |
+------------------------------+----------------+------+-----------+
Table 4: New Content-Format
TBD1 is to be assigned from the space 256..999.
In the registry as defined by Section 12.3 of [RFC7252] at the time
of writing, the column "Content-Type" is called "Media type" and the
column "Content Coding" is called "Encoding".
6. Normative References
[IANA.cbor-tags]
IANA, "Concise Binary Object Representation (CBOR) Tags",
<https://www.iana.org/assignments/cbor-tags>.
[IANA.core-parameters]
IANA, "Constrained RESTful Environments (CoRE)
Parameters",
<https://www.iana.org/assignments/core-parameters>.
[IANA.media-types]
IANA, "Media Types",
<https://www.iana.org/assignments/media-types>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/info/rfc7252>.
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
<https://www.rfc-editor.org/info/rfc7807>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
Fossati & Bormann Expires 29 October 2022 [Page 9]
Internet-Draft CoRE Problem Details April 2022
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[STD94] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/info/rfc8949>.
Acknowledgments
Mark Nottingham and Erik Wilde, authors of RFC 7807. Klaus Hartke
and Jaime Jiménez, co-authors of an earlier generation of this
specification. Christian Amsüss and Marco Tiloca for review and
comments on this document.
Authors' Addresses
Thomas Fossati
arm
Email: thomas.fossati@arm.com
Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Fossati & Bormann Expires 29 October 2022 [Page 10]