One document matched: draft-vanderstok-core-patch-00.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 RFC3864 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3864.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 RFC7252 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7252.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-00"
     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>Jacobs University</organization>
      <address>
        <postal>
          <street>Campus Ring 1</street>
          <city>Bremen</city>
          <code>28759</code>
          <country>Germany</country>
        </postal>
        <email>s.anuj@jacobs-university.de</email>
      </address>
    </author>



    <date/>

    <area>Applications</area>

    <workgroup>core</workgroup>

    <keyword>CoAP</keyword>

    <keyword>Patch</keyword>

    <abstract>
      <t>Several applications (for example see <xref
      target="I-D.vanderstok-core-comi"/>) which extend the
      Constrained Application Protocol <xref target="RFC7252"/> (CoAP)
      need to perform partial resource modifications.  The existing
      CoAP PUT method only allows a complete replacement of a
      resource. This proposal adds a new CoAP method, PATCH, 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"/> method, PATCH, which
	is 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.
      </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 mentioned in an early design stage
	of CoAP but was deemed unnecessarily complicated. With the
	arrival of the Constrained Management Interface (CoMI)
	protocol, <xref target="I-D.vanderstok-core-comi"/>, the need
	to do partial changes to resources specified with YANG becomes
	more acute. Applications might wish to make to changes to
	parts of a YANG data resource, and transferring all data
	associated with a YANG data resource unnecessarily burdens 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 Method">
      <t>
	The PATCH method requests that a set of changes described in
	the request payload is applied to the resource identified by
	the Request-URI.  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, resulting in a 2.01 (Created) Response
	Code.  Restrictions to a PATCH 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 but idempotent conformant to CoAP PUT
	specified in <xref target="RFC7252"/>, Section 5.8.3.
      </t>
      <t>
	PATCH can use confirmable (CON) or Non-confirmable (NON) CoAP
	requests. It is recommended to use the CON version of the
	PATCH command. 
      </t>
      <t> 
	A PATCH request is idempotent to prevent bad outcomes from
	collisions between two PATCH 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>
	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. In general,
	modifications MUST NOT be executed when an error occurs or
	only a partial execution is possible.  The atomicity
	requirement holds for all directly affected (sub)resources.
	See "Response Codes", <xref target="response"/>, for details
	on status codes and possible error conditions.
      </t>
      <t>
	If the request passes through a cache and the Request-URI
	identifies one or more currently cached responses, those
	responses SHOULD be treated as being stale.  A cached PATCH
	response can only be used to respond to subsequent GET
	requests; it MUST NOT be used to respond to other methods (in
	particular, PATCH).
      </t>
      <t>
	There is no guarantee that a resource can be modified with
	PATCH. 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 Request-URI.  
      </t>
      <t> 
	Clients MUST choose to use PATCH rather than PUT when the
	request affects (sub)resources of a given resource.
      </t>

      <section anchor="example" title="A Simple PATCH Example">
	<t>
	</t>
	<figure><artwork align="left">
	  <![CDATA[ 
		   REQ: PATCH
		        coap://www.example.com/object/sub1 
		        payload with changes 
		   RET:
		        CoAP 2.04 Changed
	]]></artwork></figure>

	<t>
	  This example illustrates use of a hypothetical PATCH on the
	  sub resource /object/sub1 of the existing resource "object".
	  The 2.04 (Changed) response code is conforms with the CoAP
	  PUT method.
	</t>
      </section>  <!-- patch example -->

      <section anchor="response" title= "Response Codes">
	<t>
	  PATCH for CoAP adopts 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 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 can also be secured by those new techniques.
	</t>
      </section> <!-- Securing patch  -->

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

    <section anchor="errors" title="Error Handling">
      <t>
	A PATCH 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 payload:">If a server
	  determines that the payload provided with a PATCH 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 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 X.XX CoAP error. Such a scenario might include
	  situations when:</t>
	  <t><list style="symbols">
	    <t>the server has insufficient computing resources to
	    complete the request successfully,</t>
	    <t>the resource specified in the request becomes invalid
	    by applying the payload,</t>
	    <t>modifying a resource leads to a conflicting state.</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 modification:">In situations when a
	  server detects possible conflicting modifications and no
	  precondition is defined in the requests, the server can
	  return a X.XX CoAP status.</t>
	  <t hangText="Conflicting state:">If the modification
	  specified by a PATCH request cannot be applied to a resource
	  in its current state, or causes the resource to enter an
	  inconsistent state the server can return the X.XX CoAP
	  status. 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
	  or lead the device into an inconsistent state if the
	  modifications are made.</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 X.XX CoAP status.</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
	protocol.  It is meant to inform protocol and application
	developers about the security limitations of CoAP PATCH 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 are
	nearly identical to the security considerations for PUT (<xref
	target="RFC7252"/>).  Whatever mechanisms are used for PUT can
	be used for PATCH as well.
      </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 addition will follow the "IETF Review or
	IESG Approval" procedure as described in <xref
	target="RFC5226"/>.
      </t>
    </section>   <!-- IANA considerations  -->

    <section title="Acknowledgements">
      <t>
	This document reflects discussions and remarks from several
	individuals including (in alphabetical order):
      </t>
    </section>  <!-- Acknowledgements -->

    <section title="Change log">
      <t>
	When published as a RFC, this section needs to be removed.	
      </t>
    </section>  <!-- Change log -->

  </middle>

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

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