Consultant

consultancy@vanderstok.org

Universitaet Bremen TZI

Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org

Consultant

anuj@iurs.org

Applications core CoAP The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where a resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP will need to perform partial resource accesses. This specification defines the new CoAP methods, FETCH, PATCH and iPATCH, which are used to access and update parts of a resource.

Similar to HTTP, the GET method defined in for the Constrained Application Protocol (CoAP) only allows the specification of a URI and request parameters in CoAP options, not the transfer of a request payload detailing the request. This leads to some applications to using POST where actually a cacheable, idempotent, safe request is desired. Again similar to the original specification of HTTP, the PUT method defined in only allows to replace a complete resource. This also leads applications to use POST where actually a cacheable, possibly idempotent request is desired. The present specification adds new CoAP methods: FETCH, to perform the equivalent of a GET with a request body; and the twin methods PATCH and iPATCH, to modify parts of a CoAP resource.

The CoAP GET method is used to obtain the representation of a resource, where the resource is specified by a URI and additional request parameters can additionally shape the representation. This has been modelled after the HTTP GET operation and the REST model in general. In HTTP, a resource is often used to search for information, and existing systems varyingly use the HTTP GET and POST methods to perform a search. Often a POST method is used for the sole reason that a larger set of parameters to the search can be supplied in the request body than can comfortably be transferred in the URI with a GET request. The draft proposes a SEARCH method that is similar to GET in most properties but enables sending a request body as with POST. The FETCH method defined in the present specification is inspired by , which updates the definition and semantics of the HTTP SEARCH request method previously defined by . However, there is no intention to limit FETCH to search-type operations, and the resulting properties may not be the same as those of HTTP SEARCH. A major problem with GET is that the information that controls the request needs to be bundled up in some unspecified way into the URI. Using the request body for this information has a number of advantages: The client can specify a media type (and a content encoding), enabling the server to unambiguously interpret the request parameters in the context of that media type. Also, the request body is not limited by the character set limitations of URIs, enabling a more natural (and more efficient) representation of certain domain-specific parameters. The request parameters are not limited by the maximum size of the URI. In HTTP, that is a problem as the practical limit for this size varies. In CoAP, another problem is that the block-wise transfer is not available for transferring large URI options in multiple rounds. As an alternative to using GET, many implementations make use of the POST method to perform extended requests, even if they are semantically idempotent, safe, and even cacheable, to be able to pass along the input parameters within the request payload as opposed to using the request URI. The FETCH method provides a solution that spans the gap between the use of GET and POST. As with POST, the input to the FETCH operation is passed along within the payload of the request rather than as part of the request URI. Unlike POST, however the semantics of the FETCH method are more specifically defined.

PATCH is also specified for HTTP in . Most of the motivation for PATCH described in also applies here. iPATCH is the idempotent version of PATCH. The PUT method exists to overwrite a resource with completely new contents, and cannot be used to perform partial changes. When using PUT for partial changes, proxies and caches, and even clients and servers, may get confused as to the result of the operation. PATCH was not adopted in an early design stage of CoAP, however, it has become necessary with the arrival of applications that require partial updates to resources (e.g. ). Using PATCH avoids transferring all data associated with a resource in case of modifications, thereby not burdening the constrained communication medium. This document relies on knowledge of the PATCH specification for HTTP . This document provides extracts from to make independent reading possible.

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 .

This document uses terminology defined in and . Specifically, it uses the terms “safe” and “idempotent” as defined in Section 5.1 of . (Further discussion of safe and idempotent methods can now be found in Section 4.2.1 and 4.2.2 of , respectively; the implications of idempotency of methods on server implementations are also discussed in Section 4.5 of .)

The CoAP FETCH method is used to obtain a representation of a resource, giving a number of request parameters. Unlike the CoAP GET method, which requests that a server return a representation of the resource identified by the effective request URI (as defined by ), the FETCH method is used by a client to ask the server to produce a representation as described by the request parameters (including the request options and the payload) based on the resource specified by the effective request URI. The payload returned in response to a FETCH cannot be assumed to be a complete representation of the resource identified by the effective request URI, i.e., it cannot be used by a cache as a payload to be returned by a GET request. Together with the request options, the body of the request (which may be constructed from multiple payloads using the block protocol ) defines the request parameters. Implementations may submit a request body of any media type with the FETCH method; it is outside the scope of this document how information about admissible media types is obtained by the client (although we can hint that form relations () might be a preferred way). FETCH requests are both safe and idempotent with regards to the resource identified by the request URI. That is, the performance of a fetch is not intended to alter the state of the targeted resource. (However, while processing a search request, a server can be expected to allocate computing and memory resources or even create additional server resources through which the response to the search can be retrieved.) A successful response to a FETCH request is expected to provide some indication as to the final disposition of the requested operation. If a successful response includes a body payload, the payload is expected to describe the results of the FETCH operation. Depending on the response code as defined by , the response to a FETCH request is cacheable; the request body is part of the cache key. Specifically, 2.05 “Content” response codes, the responses for which are cacheable, are a usual way to respond to a FETCH request. (Note that this aspect differs markedly from .) (Note also that caches that cannot use the request payload as part of the cache key will not be able to cache responses to FETCH requests at all.) The Max-Age option in the response has equivalent semantics to its use in a GET. The semantics of the FETCH method change to a “conditional FETCH” if the request message includes an If-Match, or If-None-Match option (). A conditional FETCH requests that the query be performed only under the circumstances described by the conditional option(s). It is important to note, however, that such conditions are evaluated against the state of the target resource itself as opposed to the results of the FETCH operation.

FETCH for CoAP adopts the response codes as specified in sections 5.9 and 12.1.2 of .

FETCH for CoAP adopts the option numbers as specified in sections 5.10 and 12.2 of . Generally, options defined for GET act in an analogous way for FETCH. Two specific cases are called out in the rest of this section.

A FETCH request MUST include a Content-Format option (see Section 5.10.3 of ) to specify the media type and content encoding of the request body. (Typically, the media type will specifically have been designed to specify details for a selection or a search on a resource.)

The ETag Option on a FETCH result has the same semantics as defined in Section 5.10.6 of . In particular, its use as a response option describes the “tagged representation”, which for FETCH is the same as the “selected representation”. The FETCH payload is input to that selection process and therefore needs to be part of the cache key. Similarly, the use of ETag as a request option can elicit a 2.03 Valid response if the representation associated with the ETag would still be selected by the FETCH request (including its payload).

The Observe option can be used with a FETCH request as it can be used with a GET request.

The Block1 option can be used with a FETCH request as it would be used with a POST request; the Block2 option can then be used as with GET or POST.

One property of FETCH that may be non-obvious is that a FETCH request cannot be generated from a link alone, but also needs a way to generate the request payload. Again, form relations () may be able to fill parts of this gap.

The FETCH method needs a media type for its payload (as expressed by the Content-Format request option) that specifies the search query in a similar detail as is shown for the patch payload in the PATCH example in . ( invents a text/query format based on some hypothetical SQL dialect for its examples.) The example below illustrates retrieval of a subset of a JSON object (the same object as used in ). Using a hypothetical media type application/example-map-keys+json (with a Content-Format ID of NNN – not defined as this is just an example), the client specifies the items in the object that it wants: it supplies a JSON array giving the map keys for these items. A resource located at coap://www.example.com/object can be represented by a JSON document that we will consider as the target of the FETCH. The client wants to learn the contents of the single map key foo within this target:

The example FETCH request specifies a single top-level member desired by giving its map key as the sole element of the example-map-keys payload:

The server returns a subset document with just the selected member:

By the logic of this example, the requester could have entered more than one map key into the request payload array and would have received a more complete subset of the top-level JSON object that is representing the resource.

The PATCH and iPATCH methods request that a set of changes described in the request payload is applied to the target resource of the request. The set of changes is represented in a format identified by a media type. If the Request-URI does not point to an existing resource, the server MAY create a new resource with that URI, depending on the patch document type (whether it can logically modify a null resource) and permissions, etc. Creation of a new resource would result in a 2.01 (Created) Response Code dependent on the patch document type. Restrictions to a PATCH or iPATCH request can be made by including the If-Match or If-None-Match options in the request (see Section 5.10.8.1 and 5.10.8.2 of ). If the resource could not be created or modified, then an appropriate Error Response Code SHOULD be sent. The difference between the PUT and PATCH requests is documented in . The PATCH method is not safe and not idempotent, as with the HTTP PATCH method specified in . The iPATCH method is not safe but idempotent, as with the CoAP PUT method specified in , Section 5.8.3. A client can mark a request as idempotent by using the iPATCH method instead of the PATCH method. This is the only difference between the two. The indication of idempotence may enable the server to keep less state about the interaction; some constrained servers may only implement the iPATCH variant for this reason. PATCH and iPATCH are both atomic. The server MUST apply the entire set of changes atomically and never provide a partially modified representation to a concurrently executed GET request. Given the constrained nature of the servers, most servers will only execute CoAP requests consecutively, thus preventing a concurrent partial overlapping of request modifications. Resuming, modifications MUST NOT be applied to the server state when an error occurs or only a partial execution is possible on the resources present in the server. The atomicity applies to a single server. When a PATCH or iPATCH request is multicast to a set of servers, each server can either execute all required modifications or not. It is not required that all servers execute all modifications or none. An Atomic Commit protocol that provides multiple server atomicity is out of scope. A PATCH or iPATCH response can invalidate a cache as with the PUT response. Caching behaviour as function of the successful (2.xx) response codes for PATCH or iPATCH are: A 2.01 (Created) response invalidates any cache entry for the resource indicated by the Location-* Options; the payload is a representation of the action result. A 2.04 (Changed) response invalidates any cache entry for the target resource; the payload is a representation of the action result. There is no guarantee that a resource can be modified with PATCH or iPATCH. Servers MUST ensure that a received PATCH body is appropriate for the type of resource identified by the target resource of the request. When a request is intended to effect a partial update of a given resource, clients cannot use PUT while supplying just the update, but are free to use PATCH or iPATCH.

The example is taken over from , which specifies a JSON notation for PATCH operations. A resource located at coap://www.example.com/object contains a target JSON document.

This example illustrates use of an idempotent modification to the x-coord member of the existing resource “object”. The 2.04 (Changed) response code is conform with the CoAP PUT method. The same example using the Content-Format application/merge-patch+json from looks like:

The examples show the use of the iPATCH method, but the use of the PATCH method would have led to the same result. Below a non-idempotent modification is shown. Because the action is non-idempotent, iPATCH returns an error, while PATCH executes the action.

PATCH and iPATCH for CoAP adopt the response codes as specified in sections 5.9 and 12.1.2 of and add 4.09 “Conflict” and 4.22 “Unprocessable Entity” with the semantics specified in of the present specification.

PATCH and iPATCH for CoAP adopt the option numbers as specified in sections 5.10 and 12.2 of .

A PATCH or iPATCH request may fail under certain known conditions. These situations should be dealt with as expressed below. If a server determines that the payload provided with a PATCH or iPATCH request is not properly formatted, it can return a 4.00 (Bad Request) CoAP error. The definition of a malformed payload depends upon the CoAP Content-Format specified with the request. In case a client sends payload that is inappropriate for the resource identified by the Request-URI, the server can return a 4.15 (Unsupported Content-Format) CoAP error. The server can determine if the payload is supported by checking the CoAP Content-Format specified with the request. This situation occurs when the payload of a PATCH request is determined as valid, i.e. well-formed and supported, however, the server is unable to or incapable of processing the request. The server can return a 4.22 (Unprocessable Entity) CoAP error. More specific scenarios might include situations when: the server has insufficient computing resources to complete the request successfully — 4.13 (Request Entity Too Large) CoAP Response Code (see below), the resource specified in the request becomes invalid by applying the payload — 4.09 (Conflict) CoAP Response Code (see below)). In case there are more specific errors that provide more insight into the problem, then those should be used. The 4.04 (Not Found) error should be returned in case the payload of a PATCH request cannot be applied to a non-existent resource. In case the client uses the conditional If-Match or If-None-Match option to define a precondition for the PATCH request, and that precondition fails, then the server can return the 4.12 (Precondition Failed) CoAP error. If the payload of the PATCH request is larger than a CoAP server can process, then it can return the 4.13 (Request Entity Too Large) CoAP error. If the modification specified by a PATCH or iPATCH request causes the resource to enter an inconsistent state that the server cannot resolve, the server can return the 4.09 (Conflict) CoAP response. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict. The server MAY return the actual resource state to provide the client with the means to create a new consistent resource state. Such a situation might be encountered when a structural modification is applied to a configuration data-store, but the structures being modified do not exist. Resource constrained devices might need to process requests in the order they are received. In case requests are received concurrently to modify the same resource but they cannot be queued, the server can return a 5.03 (Service unavailable) CoAP response code. If the modification implies the reservation of resources or the waiting on conditions to become true, leading to a too long request execution time, the server can return 5.03 (service unavailable) response code. It is possible that other error situations, not mentioned here, are encountered by a CoAP server while processing the PATCH request. In these situations other appropriate CoAP status codes can also be returned.

Adding three new methods to CoAP’s existing four may seem like a major change. However, both FETCH and the two PATCH variants fit well into the REST paradigm and have been anticipated on the HTTP side. Adding both a non-idempotent and an idempotent PATCH variant allows to keep interoperability with HTTP’s PATCH method as well as the use/indication of an idempotent PATCH if that is possible, saving significant effort on the server side. Interestingly, the three new methods fit into the old table of methods with a surprising similarity in the idempotence and safety attributes: Code Name Code Name safe idempotent 0.01 GET 0.05 FETCH yes yes 0.02 POST 0.06 PATCH no no 0.03 PUT 0.07 iPATCH no yes 0.04 DELETE     no yes

This section analyses the possible threats to the CoAP FETCH and PATCH or iPATCH methods. It is meant to inform protocol and application developers about the security limitations of CoAP FETCH and PATCH or iPATCH as described in this document. The FETCH method is subject to the same general security considerations as all CoAP methods as described in . The security consideration of Section 11 of as well as those of Section 5 of also apply. The security considerations for PATCH or iPATCH are nearly identical to the security considerations for PUT (). The mechanisms used for PUT can be used for PATCH or iPATCH as well. PATCH or iPATCH are secured following the CoAP recommendations as specified in section 9 of . When additional security techniques are standardized for CoAP, PATCH or iPATCH can also be (and need to be) secured by those new techniques.

IANA is requested to add the following entries to the sub-registry “CoAP Method Codes”: Code Name Reference 0.05 FETCH [RFCthis] 0.06 PATCH [RFCthis] 0.07 iPATCH [RFCthis] The FETCH method is idempotent and safe, and it returns the same response codes that GET can return, plus 4.15 “Unsupported Content-Format” with the same semantics as with POST. The PATCH method is neither idempotent nor safe. It returns the same response codes that POST can return, plus 4.09 “Conflict” and 4.22 “Unprocessable Entity” with the semantics specified in . The iPATCH method is identical to the PATCH method, except that it is idempotent. IANA is requested to add the following code to the sub-registry “CoAP response codes”: Code Name Reference 4.09 Conflict [RFCthis] 4.22 Unprocessable Entity [RFCthis] IANA is requested to add entries to the sub-registry “CoAP Content-Formats”, within the “CoRE Parameters” registry: Media Type Encoding ID Reference application/json-patch+json   51 application/merge-patch+json   52

When published as an RFC, this section needs to be removed. Version 00 is a composition from draft-vanderstok-core-patch-03 and draft-bormann-core-coap-fetch-00 and replaces these two drafts. Version 01 added an example for FETCH and is more explicit about some response codes and options. Version 02 addresses the WGLC comments. Version 03 addresses the IETF last-call comments.

In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification. The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation. 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. The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. 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. This document specifies a set of methods, headers, and properties composing Web Distributed Authoring and Versioning (WebDAV) SEARCH, an application of the HTTP/1.1 protocol to efficiently search for DAV resources based upon a set of client-supplied criteria. [STANDARDS-TRACK] JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JavaScript Object Notation (JSON) document; it is suitable for use with the HTTP PATCH method. The "application/json-patch+json" media type is used to identify such patch documents. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This specification defines the JSON merge patch format and processing rules. The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This document describes a network management interface for constrained devices, called CoMI. CoMI is an adaptation of the RESTCONF protocol for use in constrained devices and networks. The Constrained Application Protocol (CoAP) is used to access management data resources specified in YANG, or SMIv2 converted to YANG. CoMI use the YANG to CBOR mapping and encodes YANG names to reduce payload size. Note Discussion and suggestions for improvement are requested, and should be sent to core@ietf.org. The interfaces of RESTful, hypertext-driven applications consist of reusable components such as Internet media types and link relation types. This document defines a simple standard that application designers can use to describe the interface of their application in a structured way so that other parties can develop interoperable clients and servers or reuse the components in their own applications. Note to Readers This Internet-Draft should be discussed on the Thing-to-Thing Research Group (T2TRG) mailing list <t2trg@irtf.org>. This specification updates the definition and semantics of the HTTP SEARCH request method previously defined by [RFC5323].

Klaus Hartke has pointed out some essential differences between CoAP and HTTP concerning PATCH, and found a number of problems in an earlier version of . We are grateful for discussions with Christian Amsuss, Andy Bierman, Timothy Carey, Paul Duffy, Matthias Kovatsch, Michel Veillette, Michael Verschoor, Thomas Watteyne, and Gengyu Wei. Christian Groves provided detailed comments during the Working-Group Last Call, and Christer Holmberg’s Gen-ART review provided some further editorial improvement. Further last-call reviews were provided by Sheng Jiang and Phillip Hallam-Baker.