core                                                     P. van der Stok
Internet-Draft                                                 A. Sehgal
Intended status: Informational                                Consultant
Expires: January 7, 2016                                    July 6, 2015


        Patch Method for Constrained Application Protocol (CoAP)
                     draft-vanderstok-core-patch-01

Abstract

   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 a new CoAP method, PATCH,
   to modify an existing CoAP resource partially.

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 http://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 January 7, 2016.

Copyright Notice

   Copyright (c) 2015 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
   (http://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



van der Stok & Sehgal    Expires January 7, 2016                [Page 1]


Internet-Draft                 CoAP Patch                      July 2015


   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   3
     1.2.  Terminology and Acronyms  . . . . . . . . . . . . . . . .   3
   2.  Patch Method  . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  A Simple PATCH Example  . . . . . . . . . . . . . . . . .   4
     2.2.  Response Codes  . . . . . . . . . . . . . . . . . . . . .   5
     2.3.  Option Numbers  . . . . . . . . . . . . . . . . . . . . .   5
   3.  Error Handling  . . . . . . . . . . . . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   6.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   7
   7.  Change log  . . . . . . . . . . . . . . . . . . . . . . . . .   7
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     8.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   This specification defines the new Constrained Application Protocol
   (CoAP) [RFC7252] method, PATCH, which is used to apply partial
   modifications to a resource.

   PATCH is also specified for HTTP in [RFC5789].  Most of the
   motivation for PATCH described in [RFC5789] also applies here.

   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.  [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.

   This document relies on knowledge of the PATCH specification for HTTP
   [RFC5789].  This document provides extracts from [RFC5789] to make
   independent reading possible.





van der Stok & Sehgal    Expires January 7, 2016                [Page 2]


Internet-Draft                 CoAP Patch                      July 2015


1.1.  Requirements Language

   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 [RFC2119].

1.2.  Terminology and Acronyms

   This document uses terminology defined in [RFC5789] and [RFC7252].

2.  Patch Method

   The PATCH 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.

   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 [RFC7252]).  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 extensively
   documented in [RFC5789].

   PATCH is not safe but idempotent conformant to CoAP PUT specified in
   [RFC7252], Section 5.8.3.

   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
   [RFC7252].

   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 applied to the server state
   when an error occurs or only a partial execution is possible.  The
   atomicity requirement holds for all directly affected resources.





van der Stok & Sehgal    Expires January 7, 2016                [Page 3]


Internet-Draft                 CoAP Patch                      July 2015


   A PATCH response can invalidate a cache conformant with the PUT
   response.  Caching behaviour as function of the valid 2.xx response
   codes for PATCH 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.
   Servers are required to support a subset of the content formats as
   specified in sections 12.3 and 5.10.3 of [RFC7252].  Servers MUST
   ensure that a received PATCH payload is appropriate for the type of
   resource identified by the target resource of the request.

   Clients MUST choose to use PATCH rather than PUT when the request
   affects partial updates of a given resource.

2.1.  A Simple PATCH Example

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


           JSON document orginal state
                {
                   "x-coord": 256,
                   "y-coord": 45
                }

                      REQ:
                     PATCH CoAP://www.example.com/object
                      [
                    { "op":"replace","path":"x-coord","value":45}
                 ]
                      RET:
                           CoAP 2.04 Changed

           JSON document final state
                {
                   "x-coord": 45,
                   "y-coord": 45
                }




van der Stok & Sehgal    Expires January 7, 2016                [Page 4]


Internet-Draft                 CoAP Patch                      July 2015


   This example illustrates use of a hypothetical PATCH on the /object/
   x-coord of the existing resource "object".  The 2.04 (Changed)
   response code is conforms with the CoAP PUT method.

2.2.  Response Codes

   PATCH for CoAP adopts the response codes as specified in sections 5.9
   and 12.1.2 of [RFC7252].

2.3.  Option Numbers

   PATCH for CoAP adopts the option numbers as specified in sections
   5.10 and 12.2 of [RFC7252].

3.  Error Handling

   A PATCH request may fail under certain known conditions.  These
   situations should be dealt with as expressed below.

   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.

   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.

   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:

      *  the server has insufficient computing resources to complete the
         request successfully -- 4.13 (Request Entity Too Large) CoAP
         Response Code,

      *  the resource specified in the request becomes invalid by
         applying the payload -- 4.06 (Not Acceptable) CoAP Response
         Code,

      In case there are more specific errors that provide more insight
      into the problem, then those should be used.



van der Stok & Sehgal    Expires January 7, 2016                [Page 5]


Internet-Draft                 CoAP Patch                      July 2015


   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.

   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.

   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 4.09 (Conflict) CoAP response.  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.

   Conflicting modification:  In situations when a server detects
      possible conflicting modifications the server can return a 4.nr2
      CoAP response code.

   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 4.09 (Conflict) CoAP
      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.

4.  Security Considerations

   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 [RFC2616],
   section 11 of [RFC7252], and section 5 of [RFC5789] also apply.

   The security considerations for PATCH are nearly identical to the
   security considerations for PUT ([RFC7252]).  The mechanisms used for
   PUT can be used for PATCH as well.

   PATCH is secured following the CoAP recommendations as specified in
   section 9 of [RFC7252].  When more appropriate security techniques
   are standardized for CoAP, PATCH can also be secured by those new
   techniques.



van der Stok & Sehgal    Expires January 7, 2016                [Page 6]


Internet-Draft                 CoAP Patch                      July 2015


5.  IANA Considerations

   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 [RFC5226].

   TODO, definition of CoAP response code 4.09 for addition to the sub-
   registry of CoAP response codes.

   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" [RFC6902], and "application/
   merge-patch+json" [RFC7386].

6.  Acknowledgements

   Klaus Hartke has pointed out some essential differences between CoAP
   and HTTP.  We are grateful for discussions with Carsten Bormann,
   Kovatsch Matthias, and Thomas Watteyne.

7.  Change log

   When published as a RFC, this section needs to be removed.

   Version 0 to version 1:

   o  Changed patch motivation text.

   o  Removed sub-resource concept.

   o  Updated cache handling.

   o  Extended example.

   o  Update of error handling.

8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.





van der Stok & Sehgal    Expires January 7, 2016                [Page 7]


Internet-Draft                 CoAP Patch                      July 2015


   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              May 2008.

   [RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC
              5789, March 2010.

   [RFC6902]  Bryan, P. and M. Nottingham, "JavaScript Object Notation
              (JSON) Patch", RFC 6902, April 2013.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252, June 2014.

   [RFC7386]  Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7386,
              October 2014.

8.2.  Informative References

   [I-D.vanderstok-core-comi]
              Stok, P., Greevenbosch, B., Bierman, A., Schoenwaelder,
              J., and A. Sehgal, "CoAP Management Interface", draft-
              vanderstok-core-comi-06 (work in progress), February 2015.

Authors' Addresses

   Peter van der Stok
   Consultant

   Email: consultancy@vanderstok.org


   Anuj Sehgal
   Consultant

   Email: anuj@iurs.org
















van der Stok & Sehgal    Expires January 7, 2016                [Page 8]