One document matched: draft-vanderstok-core-patch-03.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'[
<!ENTITY RFC2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2616 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC5226 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">
<!ENTITY RFC5789 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml">
<!ENTITY RFC6902 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6902.xml">
<!ENTITY RFC7252 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7252.xml">
<!ENTITY RFC7396 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7396.xml">
<!ENTITY I-D.vanderstok-core-comi SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.vanderstok-core-comi.xml">
]>

<?rfc toc="yes" tocompact="yes" tocdepth="3" tocindent="yes" symrefs="yes" sortrefs="no" comments="yes" inline="yes" compact="yes" subcompact="no"?>
<?rfc symrefs="yes"?>
<rfc category="info" docName="draft-vanderstok-core-patch-03"
     ipr="trust200902">
  <front>
    <title abbrev="CoAP Patch">
    Patch Method for Constrained Application Protocol (CoAP)
    </title>

    
    <author fullname="Peter van der Stok" initials="P." surname="van der Stok">
      <organization>Consultant</organization>

      <address>
        <email>consultancy@vanderstok.org</email>
      </address>
    </author>

    <author fullname="Anuj Sehgal" initials="A"
            surname="Sehgal">
      <organization>Consultant</organization>
      <address>
        <!--<postal>
          <street>Zum Rusch 1</street>
          <city>Bremen</city>
          <code>28717</code>
          <country>Germany</country>
        </postal>-->
        <email>anuj@iurs.org</email>
      </address>
    </author>



    <date/>

    <area>Applications</area>

    <workgroup>core</workgroup>

    <keyword>CoAP</keyword>

    <keyword>Patch</keyword>

    <abstract>
      <t>
	The existing Constrained Application Protocol (CoAP) PUT
	method only allows a complete replacement of a resource. This
	does not permit applications to perform partial resource
	modifications. In case of resources with larger or complex
	data, or in situations where a resource continuity is
	required, replacing a resource is not an option. Several
	applications using CoAP will need to perform partial resource
	modifications. This proposal adds new CoAP methods, PATCH and iPATCH, to
	modify an existing CoAP resource partially.
      </t>
    </abstract>
  </front>

  <middle>
    <section anchor="intro" title="Introduction">
      
      <t>
	This specification defines the new Constrained Application
	Protocol (CoAP) <xref target="RFC7252"/> methods, PATCH and iPATCH, which
	are used to apply partial modifications to a resource.  
      </t>
      <t>
	PATCH is also specified for HTTP in <xref
	target="RFC5789"/>. Most of the motivation for PATCH described
	in <xref target="RFC5789"/> also applies here. iPATCH is the idem-potent version of PATCH.
      </t>
      <t> 
	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. <xref target="I-D.vanderstok-core-comi"/>). Using PATCH
	avoids transferring all data associated with a resource in
	case of modifications, thereby not burdening the constrained
	communication medium.
      </t>
      <t> 
	This document relies on knowledge of the PATCH specification
	for HTTP <xref target="RFC5789"/>. This document provides
	extracts from <xref target="RFC5789"/> to make independent
	reading possible.
      </t>

      <section title="Requirements Language">
        <t>
	  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
	  "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
	  and "OPTIONAL" in this document are to be interpreted as
	  described in <xref target="RFC2119"/>.
	</t>
      </section>  <!-- Requirements language -->

      <section title="Terminology and Acronyms">
	<t>
	  This document uses terminology defined in <xref
	  target="RFC5789"/> and <xref target="RFC7252"/>.
	</t>
      </section>   <!-- terminology -->
      
    </section>   <!-- Introduction -->

    <section anchor="patch" title="PATCH (iPATCH) Method">
      <t>
	The PATCH (iPATCH) method requests 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 of the patch document type.
      </t>
      <t>
	Restrictions to a PATCH (iPATCH) 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 <xref target="RFC7252"/>).  If the resource
	could not be created or modified, then an appropriate Error
	Response Code SHOULD be sent.
      </t>
      <t> 
	The difference between the PUT and PATCH requests is
	extensively documented in <xref target="RFC5789"/>.
      </t>
      <t>PATCH is not safe and not idempotent conformant to HTTP  PATCH
	specified in <xref target="RFC5789"/>.
      </t>
      <t> 
      iPATCH is not safe but idempotent conformant to CoAP PUT
	specified in <xref target="RFC7252"/>, Section 5.8.3.
      </t>
      <t> 
	An iPATCH request is idempotent to prevent bad outcomes from
	collisions between two iPATCH requests on the same resource in
	a similar time frame. These collisions can be detected with
	the MessageId and the source end-point provided by the CoAP
	protocol (see section 4.5 of <xref target="RFC7252"/>.
      </t>
      <t>
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.  When the PATCH request is over-specified (i.e. Request specifies modifications to attributes which do not exist in the server), The server MAY execute all modifications to existing attributes and return a response code 2.02 Accepted.
</t><t>
The atomicity applies to a single server. When a PATCH (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.
      </t>
      <t>
	A PATCH (iPATCH) response can invalidate a cache conformant with the
	PUT response. Caching behaviour as function of the valid 2.xx
	response codes for PATCH (iPATCH) are: </t>
      <t>
	<list style="empty">
	  <t>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.</t>
	  <t> A 2.04 (Changed) response invalidates any cache entry
	  for the target resource; the payload is a representation of
	  the action result.</t>
	</list>
      </t>
      <t>
	There is no guarantee that a resource can be modified with
	PATCH (iPATCH). Servers are required to support a subset of the content
	formats as specified in sections 12.3 and 5.10.3 of <xref
	target="RFC7252"/>.  Servers MUST ensure that a received PATCH
	payload is appropriate for the type of resource identified by
	the target resource of the request.  
      </t>
      <t> 
	Clients MUST choose to use PATCH (iPATCH) rather than PUT when the
	request affects partial updates of a given resource.
      </t>
<t>
PATCH (iPATCH) MUST not be used to restore default values to resource attributes which are not specified in the payload. PATCH (iPATCH) specifically guarantees that unspecified resource attributes are not changed.
</t>

      <section anchor="example" title="A Simple PATCH (iPATCH) Example">
	<t>
	  The example is taken over from <xref target="RFC6902"/>,
	  which specifies a JSON notation for PATCH operations. A
	  resource located at www.example.com/object contains a target
	  JSON document.
</t>
<figure><artwork align="left">
<![CDATA[ 
JSON document original state
            { 
              "x-coord": 256,
              "y-coord": 45",
              "foo": ["bar","baz"]
            }

 REQ: 
     iPATCH CoAP://www.example.com/object 
Content-Format: application/json-patch+json
         [
             { "op":"replace","path":"x-coord","value":45}
         ]
RET:
     CoAP 2.04 Changed
    
JSON document final state
            { 
               "x-coord": 45,
               "y-coord": 45,
               "foo": ["bar","baz"]
             }
	]]></artwork></figure>

	<t>
	  This example illustrates use of an idempotent modification to the
	   x-coord attribute of the existing resource "object".
	  The 2.04 (Changed) response code is conform with the CoAP
	  PUT method.
</t><t>
The same example using the Content-Format application/merge-patch+json from <xref target="RFC7396"/> looks like:
	</t>
<figure><artwork align="left">
<![CDATA[ 
JSON document original state
            { 
              "x-coord": 256,
              "y-coord": 45,
              "foo": ["bar","baz"]
            }

 REQ: 
     iPATCH CoAP://www.example.com/object 
Content-Format: application/merge-patch+json
     { "x-coord":45}
RET:
     CoAP 2.04 Changed
    
JSON document final state
            { 
               "x-coord": 45,
               "y-coord": 45,
               "foo": ["bar","baz"]
             }
	]]></artwork></figure>
<t>
The examples show the use of the iPATCH method, but the use of the PATCH method must 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.
</t>
<figure><artwork align="left">
<![CDATA[ 
JSON document original state
            { 
              "x-coord": 256,
              "y-coord": 45",
              "foo": ["bar","baz"]
            }

 REQ: 
     iPATCH CoAP://www.example.com/object 
Content-Format: application/json-patch+json
         [
             { "op":"add","path":"foo/1","value":"bar"}
         ]
RET:
     CoAP 4.12 Precondition Failed
    
JSON document final state is unchanged

REQ: 
     PATCH CoAP://www.example.com/object 
Content-Format: application/json-patch+json
         [
             { "op":"add","path":"foo/1","value":"bar"}
         ]
RET:
     CoAP 2.04 Changed

JSON document final state

            { 
               "x-coord": 45,
               "y-coord": 45,
               "foo": ["bar","bar","baz"]
             }
	]]></artwork></figure>


      </section>  <!-- patch example -->

      <section anchor="response" title= "Response Codes">
	<t>
	  PATCH (iPATCH) for CoAP adopt the response codes as specified in
	  sections 5.9 and 12.1.2 of <xref target="RFC7252"/>.
	</t>
      </section>  <!-- Response codes -->


      <section anchor="option" title= "Option Numbers">
	<t>
	  PATCH for CoAP adopts the option numbers as specified in
	  sections 5.10 and 12.2 of <xref target="RFC7252"/>.
	</t>
      </section>  <!-- Option numbers -->

      <!--<section anchor="security" title=" Securing PATCH">
	<t>
	  PATCH (iPATCH) is secured following the CoAP recommendations as
	  specified in section 9 of <xref target="RFC7252"/>. When
	  more appropriate security techniques are standardized for
	  CoAP, PATCH (iPATCH) can also be secured by those new techniques.
	</t>
      </section>--> <!-- Securing patch  -->

    </section>  <!-- Patch method -->

    <section anchor="errors" title="Error Handling">
      <t>
	A PATCH (iPATCH) request may fail under certain known conditions. These
	situations should be dealt with as expressed below.
      </t>
      <t>
	<list style="hanging">
	  <t hangText="Malformed PATCH (iPATCH) payload:">If a server
	  determines that the payload provided with a PATCH (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.</t>
	  <t hangText="Unsupported PATCH (iPATCH) payload:">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.</t>
	  <t hangText="Unprocessable 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:
	  <list style="symbols">
	    <t> the server has insufficient computing resources to
	    complete the request successfully -- 4.13 (Request Entity
	    Too Large) CoAP Response Code,</t>
	    <t> the resource specified in the request becomes invalid
	    by applying the payload -- 4.06 (Not Acceptable) CoAP
	    Response Code,</t>
	  </list>
</t>
	  <t>In case there are more specific errors that provide more
	  insight into the problem, then those should be used.</t>
	  <t hangText="Resource not found:">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.</t>
	  <t hangText="Failed precondition:">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.</t>
	  <t hangText="Request too large:">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.</t>
	  <t hangText="Conflicting state:">If the modification specified by a PATCH (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.</t>
	  <t hangText="Concurrent modification:">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.</t>
     <t hangText="Conflict handling failure:"> 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.</t>
	</list>
      </t>
      <t>
	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.
      </t>
    </section>

    <section title="Security Considerations">
      <t>
	This section analyses the possible threats to the CoAP PATCH (iPATCH)
	protocol.  It is meant to inform protocol and application
	developers about the security limitations of CoAP PATCH (iPATCH) as
	described in this document.  The security consideration of
	section 15 of <xref target="RFC2616"/>, section 11 of <xref
	target="RFC7252"/>, and section 5 of <xref target="RFC5789"/>
	also apply.
      </t>
      <t>
	The security considerations for PATCH (iPATCH) are nearly identical to
	the security considerations for PUT (<xref
	target="RFC7252"/>).  The mechanisms used for PUT can be used
	for PATCH (iPATCH) as well.
      </t>
      <t>
	PATCH (iPATCH) is secured following the CoAP recommendations as
	specified in section 9 of <xref target="RFC7252"/>. When more
	appropriate security techniques are standardized for CoAP,
	PATCH (iPATCH) can also be secured by those new techniques.
      </t>
    </section>  <!-- security consideration  -->

    <section title="IANA Considerations">
      <t> 
	The entry with name PATCH in the sub-registry, "CoAP Method
	Codes", is 0.05. The entry with name iPATCH in the sub-registry, "CoAP Method
	Codes", is 0.06. The additions will follow the "IETF Review or
	IESG Approval" procedure as described in <xref
	target="RFC5226"/>.
      </t>
      <t> A new response code must be entered to
      the sub-registry "CoAP response codes" which apply to the methods PATCH and iPATCH.
</t><t>
Code 4.09 with Description "Conflict" and described in this specification.
</t><t>
The addition to this sub-registry will follow the "IETF
Review or IESG Approval" as described in <xref target="RFC5226"/>.
</t>
<t>
Additions to the sub-registry "CoAP
Content-Formats", within the "CoRE Parameters" registry are needed for the following media type formats: "application/json-patch+json" <xref target="RFC6902"/>, and "application/merge-patch+json" <xref target="RFC7396"/>.
</t>
    </section>   <!-- IANA considerations  -->

    <section title="Acknowledgements">
      <t>
Klaus Hartke has pointed out some essential differences between CoAP and HTTP. We are grateful for discussions with Christian Amsuss, Carsten Bormann, Timothy Carey, Paul Duffy, Kovatsch Matthias, Michel Veillette, Michael Verschoor, Thomas Watteyne, and Gengyu Wei.
      </t>
    </section>  <!-- Acknowledgements -->

    <section title="Change log">
      <t>
	When published as a RFC, this section needs to be removed.	
      </t><t>
Version 0 to version 1:
<list style="symbols">
<t> Changed patch motivation text.</t>
<t> Removed sub-resource concept. </t>
<t> Updated cache handling.</t>
<t> Extended example. </t>
<t> Update of error handling.</t>
</list>
Version 1 to version 2
<list style="symbols">
<t> section 3 rephrased use of error 4.09</t>
<t> added conflict handling failure </t>
<t> added idempotent iPATCH method </t>
</list>
Version 2 to version 3
<list style="symbols">
<t> added line about default values</t>
<t> content-Type to content_Format</t>
<t> extended Patch example with non-idempotent request </t>
</list>

</t>
    </section>  <!-- Change log -->

  </middle>

  <back>
    <references title="Normative References">
	&RFC2119;
	&RFC2616;
	&RFC5226;
	&RFC5789;
     &RFC6902;
	&RFC7252;
      &RFC7396;    
    </references>

    <references title="Informative References">
      &I-D.vanderstok-core-comi;
    </references>   
  </back>
</rfc>