]>

Austria christian@amsuess.com

CoRE This defines a single standard problem detail for use with the Concise Problem Details format: Request Body Error Position. Using this detail, the server can point at the position inside the client's request body that induced the error. Discussion Venues Discussion of this document takes place on the Constrained RESTful Environments Working Group mailing list (core@ietf.org), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction Concise Problem Details for CoAP APIs describes how a server can provide details about an error processing a client request, and how to extend these error messages. This document uses that extension mechanism and adds the Request Body Error Position detail.

Terminology The description of the problem detail uses the term "body" as defined in .

Document lifecycle Registering a standard problem detail merely requires a specification, not an RFC (let alone of a particular track). It is the author's opinion that an Interned Draft can provide sufficient specification, and is more suitable than an informal note published at some arbitrary website due to its archival through the draft submission process. It is not expected that this draft will proceed all the way to an RFC; instead, once sufficiently mature, it will be used as a reference in a request to IANA, and updated with the assigned number. This document will eventually expire as an Internet Draft, but nonetheless be usable as the permanent reference for the assigned problem detail.

Request Body Error Position The Request Body Error Position problem detail indicates that the error described by the Concise Problem Details response resulted from processing the request body. The numeric value indicates a byte position inside that body that corresponds to the error. The precise error position for invalid data may vary by implementation -- for example, if a numeric value inside a CBOR () item exceeds the expected range, it may indicate the number's initial byte (typically if the implementation doesn't even implement the indicated argument size) or the argument (if it implements it). When the request's content format indicated a non-identity content coding, the offset points into the uncompressed body. Consequently, this error detail is not suitable for pointing out errors that occur during uncompressing. The main envisioned use of this option is for the client to highlight or back-annotate (eg. to counteract minification, or to display it on some diagnostic notation) the erroneous item in the request body for a human author.

Usage example The figures in this section illustrate a CoAP message exchange using CBOR bodies, and a hypothetical CoAP tool's output that utilizes this error detail.

Messages exchanged between client and server

Output of a hypothetical CoAP client that utilizes the Request Body Error Position detail

IANA considerations A new entry is requested for the "Standard Problem Detail Keys" subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry.

Key value:

The value -25 is suggested

Name:

request-body-error-position

CDDL type:

uint

Brief description:

Byte index inside the request body at which the error became apparent

Reference:

This document

Change controller:

IETF CoRE working group

References Normative References This document defines a concise "problem detail" as a way to carry machine-readable details of errors in a Representational State Transfer (REST) response to avoid the need to define new error response formats for REST APIs for constrained environments. The format is inspired by, but intended to be more concise than, the problem details for HTTP APIs defined in RFC 7807. The Constrained Application Protocol (CoAP) is a RESTful transfer protocol for constrained nodes and networks. Basic CoAP messages work well for small payloads from sensors and actuators; however, applications will need to transfer larger payloads occasionally -- for instance, for firmware updates. In contrast to HTTP, where TCP does the grunt work of segmenting and resequencing, CoAP is based on datagram transports such as UDP or Datagram Transport Layer Security (DTLS). These transports only offer fragmentation, which is even more problematic in constrained nodes and networks, limiting the maximum size of resource representations that can practically be transferred. Instead of relying on IP fragmentation, this specification extends basic CoAP with a pair of "Block" options for transferring multiple blocks of information from a resource representation in multiple request-response pairs. In many important cases, the Block options enable a server to be truly stateless: the server can handle each block transfer separately, with no need for a connection setup or other server-side memory of previous block transfers. Essentially, the Block options provide a minimal way to transfer larger representations in a block-wise fashion. A CoAP implementation that does not support these options generally is limited in the size of the representations that can be exchanged, so there is an expectation that the Block options will be widely used in CoAP implementations. Therefore, this specification updates RFC 7252. Informative References The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments.