idnits 2.17.1 draft-vanderstok-core-patch-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == It seems as if not all pages are separated by form feeds - found 0 form feeds but 10 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 5, 2015) is 3126 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-07 Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 core P. van der Stok 3 Internet-Draft A. Sehgal 4 Intended status: Informational Consultant 5 Expires: April 7, 2016 October 5, 2015 7 Patch Method for Constrained Application Protocol (CoAP) 8 draft-vanderstok-core-patch-02 10 Abstract 12 The existing Constrained Application Protocol (CoAP) PUT method only 13 allows a complete replacement of a resource. This does not permit 14 applications to perform partial resource modifications. In case of 15 resources with larger or complex data, or in situations where a 16 resource continuity is required, replacing a resource is not an 17 option. Several applications using CoAP will need to perform partial 18 resource modifications. This proposal adds new CoAP methods, PATCH 19 and iPATCH, to modify an existing CoAP resource partially. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on April 7, 2016. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 57 1.2. Terminology and Acronyms . . . . . . . . . . . . . . . . 3 58 2. PATCH (iPATCH) Method . . . . . . . . . . . . . . . . . . . . 3 59 2.1. A Simple PATCH (iPATCH) Example . . . . . . . . . . . . . 4 60 2.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 6 61 2.3. Option Numbers . . . . . . . . . . . . . . . . . . . . . 6 62 3. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 6 63 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 64 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 65 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 66 7. Change log . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 69 8.2. Informative References . . . . . . . . . . . . . . . . . 10 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 72 1. Introduction 74 This specification defines the new Constrained Application Protocol 75 (CoAP) [RFC7252] methods, PATCH and iPATCH, which are used to apply 76 partial modifications to a resource. 78 PATCH is also specified for HTTP in [RFC5789]. Most of the 79 motivation for PATCH described in [RFC5789] also applies here. iPATCH 80 is the idem-potent version of PATCH. 82 The PUT method exists to overwrite a resource with completely new 83 contents, and cannot be used to perform partial changes. When using 84 PUT for partial changes, proxies and caches, and even clients and 85 servers, may get confused as to the result of the operation. PATCH 86 was not adopted in an early design stage of CoAP, however, it has 87 become necessary with the arrival of applications that require 88 partial updates to resources (e.g. [I-D.vanderstok-core-comi]). 89 Using PATCH avoids transferring all data associated with a resource 90 in case of modifications, thereby not burdening the constrained 91 communication medium. 93 This document relies on knowledge of the PATCH specification for HTTP 94 [RFC5789]. This document provides extracts from [RFC5789] to make 95 independent reading possible. 97 1.1. Requirements Language 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 101 document are to be interpreted as described in [RFC2119]. 103 1.2. Terminology and Acronyms 105 This document uses terminology defined in [RFC5789] and [RFC7252]. 107 2. PATCH (iPATCH) Method 109 The PATCH (iPATCH) method requests that a set of changes described in 110 the request payload is applied to the target resource of the request. 111 The set of changes is represented in a format identified by a media 112 type. If the Request-URI does not point to an existing resource, the 113 server MAY create a new resource with that URI, depending on the 114 patch document type (whether it can logically modify a null resource) 115 and permissions, etc. Creation of a new resource would result in a 116 2.01 (Created) Response Code dependent of the patch document type. 118 Restrictions to a PATCH (iPATCH) can be made by including the If- 119 Match or If-None-Match options in the request (see Section 5.10.8.1 120 and 5.10.8.2 of [RFC7252]). If the resource could not be created or 121 modified, then an appropriate Error Response Code SHOULD be sent. 123 The difference between the PUT and PATCH requests is extensively 124 documented in [RFC5789]. 126 PATCH is not safe and not idempotent conformant to HTTP PATCH 127 specified in [RFC5789]. 129 iPATCH is not safe but idempotent conformant to CoAP PUT specified in 130 [RFC7252], Section 5.8.3. 132 An iPATCH request is idempotent to prevent bad outcomes from 133 collisions between two iPATCH requests on the same resource in a 134 similar time frame. These collisions can be detected with the 135 MessageId and the source end-point provided by the CoAP protocol (see 136 section 4.5 of [RFC7252]. 138 PATCH and iPATCH are both atomic. The server MUST apply the entire 139 set of changes atomically and never provide a partially modified 140 representation to a concurrently executed GET request. Given the 141 constrained nature of the servers, most servers will only execute 142 CoAP requests consecutively, thus preventing a concurrent partial 143 overlapping of request modifications. Resuming, modifications MUST 144 NOT be applied to the server state when an error occurs or only a 145 partial execution is possible on the resources present in the server. 146 When the PATCH request is over-specified (i.e. Request specifies 147 modifications to attributes which do not exist in the server), The 148 server MAY execute all modifications to existing attributes and 149 return a response code 2.02 Accepted. 151 The atomicity applies to a single server. When a PATCH (iPATCH) 152 request is multicast to a set of servers, each server can either 153 execute all required modifications or not. It is not required that 154 all servers execute all modifications or none. An Atomic Commit 155 protocol that provides multiple server atomicity, is out of scope. 157 A PATCH (iPATCH) response can invalidate a cache conformant with the 158 PUT response. Caching behaviour as function of the valid 2.xx 159 response codes for PATCH (iPATCH) are: 161 A 2.01 (Created) response invalidates any cache entry for the 162 resource indicated by the Location-* Options; the payload is a 163 representation of the action result. 165 A 2.04 (Changed) response invalidates any cache entry for the 166 target resource; the payload is a representation of the action 167 result. 169 There is no guarantee that a resource can be modified with PATCH 170 (iPATCH). Servers are required to support a subset of the content 171 formats as specified in sections 12.3 and 5.10.3 of [RFC7252]. 172 Servers MUST ensure that a received PATCH payload is appropriate for 173 the type of resource identified by the target resource of the 174 request. 176 Clients MUST choose to use PATCH (iPATCH) rather than PUT when the 177 request affects partial updates of a given resource. 179 2.1. A Simple PATCH (iPATCH) Example 181 The example is taken over from [RFC6902], which specifies a JSON 182 notation for PATCH operations. A resource located at 183 www.example.com/object contains a target JSON document. 185 JSON document original state 186 { 187 "x-coord": 256, 188 "y-coord": 45 189 } 191 REQ: 192 PATCH CoAP://www.example.com/object 193 Content-Type: application/json-patch+json 194 [ 195 { "op":"replace","path":"x-coord","value":45} 196 ] 197 RET: 198 CoAP 2.04 Changed 200 JSON document final state 201 { 202 "x-coord": 45, 203 "y-coord": 45 204 } 206 This example illustrates use of a hypothetical PATCH on the /object/ 207 x-coord of the existing resource "object". The 2.04 (Changed) 208 response code is conforms with the CoAP PUT method. 210 The same example using the Content-Type application/merge-patch+json 211 from [RFC7396] looks like: 213 JSON document original state 214 { 215 "x-coord": 256, 216 "y-coord": 45 217 } 219 REQ: 220 PATCH CoAP://www.example.com/object 221 Content-Type: application/merge-patch+json 222 { "x-coord":45} 223 RET: 224 CoAP 2.04 Changed 226 JSON document final state 227 { 228 "x-coord": 45, 229 "y-coord": 45 230 } 232 2.2. Response Codes 234 PATCH (iPATCH) for CoAP adopt the response codes as specified in 235 sections 5.9 and 12.1.2 of [RFC7252]. 237 2.3. Option Numbers 239 PATCH for CoAP adopts the option numbers as specified in sections 240 5.10 and 12.2 of [RFC7252]. 242 3. Error Handling 244 A PATCH (iPATCH) request may fail under certain known conditions. 245 These situations should be dealt with as expressed below. 247 Malformed PATCH (iPATCH) payload: If a server determines that the 248 payload provided with a PATCH (iPATCH) request is not properly 249 formatted, it can return a 4.00 (Bad Request) CoAP error. The 250 definition of a malformed payload depends upon the CoAP Content- 251 Format specified with the request. 253 Unsupported PATCH (iPATCH) payload: In case a client sends payload 254 that is inappropriate for the resource identified by the Request- 255 URI, the server can return a 4.15 (Unsupported Content-Format) 256 CoAP error. The server can determine if the payload is supported 257 by checking the CoAP Content-Format specified with the request. 259 Unprocessable request: This situation occurs when the payload of a 260 PATCH request is determined as valid, i.e. well-formed and 261 supported, however, the server is unable to or incapable of 262 processing the request. The server can return a 4.22 263 (Unprocessable Entity) CoAP error. More specific scenarios might 264 include situations when: 266 * the server has insufficient computing resources to complete the 267 request successfully -- 4.13 (Request Entity Too Large) CoAP 268 Response Code, 270 * the resource specified in the request becomes invalid by 271 applying the payload -- 4.06 (Not Acceptable) CoAP Response 272 Code, 274 In case there are more specific errors that provide more insight 275 into the problem, then those should be used. 277 Resource not found: The 4.04 (Not Found) error should be returned in 278 case the payload of a PATCH request cannot be applied to a non- 279 existent resource. 281 Failed precondition: In case the client uses the conditional If- 282 Match or If-None-Match option to define a precondition for the 283 PATCH request, and that precondition fails, then the server can 284 return the 4.12 (Precondition Failed) CoAP error. 286 Request too large: If the payload of the PATCH request is larger 287 than a CoAP server can process, then it can return the 4.13 288 (Request Entity Too Large) CoAP error. 290 Conflicting state: If the modification specified by a PATCH (iPATCH) 291 request causes the resource to enter an inconsistent state that 292 the server cannot resolve, the server can return the 4.09 293 (Conflict) CoAP response. The server SHOULD generate a payload 294 that includes enough information for a user to recognize the 295 source of the conflict. The server MAY return the actual resource 296 state to provide the client with the means to create a new 297 consistent resource state. Such a situation might be encountered 298 when a structural modification is applied to a configuration data- 299 store, but the structures being modified do not exist. 301 Concurrent modification: Resource constrained devices might need to 302 process requests in the order they are received. In case requests 303 are received concurrently to modify the same resource but they 304 cannot be queued, the server can return a 5.03 (Service 305 unavailable) CoAP response code. 307 Conflict handling failure: If the modification implies the 308 reservation of resources or the waiting on conditions to become 309 true, leading to a too long request execution time, the server can 310 return 5.03 (service unavailable) response code. 312 It is possible that other error situations, not mentioned here, are 313 encountered by a CoAP server while processing the PATCH request. In 314 these situations other appropriate CoAP status codes can also be 315 returned. 317 4. Security Considerations 319 This section analyses the possible threats to the CoAP PATCH (iPATCH) 320 protocol. It is meant to inform protocol and application developers 321 about the security limitations of CoAP PATCH (iPATCH) as described in 322 this document. The security consideration of section 15 of 323 [RFC2616], section 11 of [RFC7252], and section 5 of [RFC5789] also 324 apply. 326 The security considerations for PATCH (iPATCH) are nearly identical 327 to the security considerations for PUT ([RFC7252]). The mechanisms 328 used for PUT can be used for PATCH (iPATCH) as well. 330 PATCH (iPATCH) is secured following the CoAP recommendations as 331 specified in section 9 of [RFC7252]. When more appropriate security 332 techniques are standardized for CoAP, PATCH (iPATCH) can also be 333 secured by those new techniques. 335 5. IANA Considerations 337 The entry with name PATCH in the sub-registry, "CoAP Method Codes", 338 is 0.05. The entry with name iPATCH in the sub-registry, "CoAP 339 Method Codes", is 0.06. The additions will follow the "IETF Review 340 or IESG Approval" procedure as described in [RFC5226]. 342 A new response code must be entered to the sub-registry "CoAP 343 response codes" which apply to the methods PATCH and iPATCH. 345 Code 4.09 with Description "Conflict" and described in this 346 specification. 348 The addition to this sub-registry will follow the "IETF Review or 349 IESG Approval" as described in [RFC5226]. 351 Additions to the sub-registry "CoAP Content-Formats", within the 352 "CoRE Parameters" registry are needed for the following media type 353 formats: "application/json-patch+json" [RFC6902], and "application/ 354 merge-patch+json" [RFC7396]. 356 6. Acknowledgements 358 Klaus Hartke has pointed out some essential differences between CoAP 359 and HTTP. We are grateful for discussions with Christian Amsuss, 360 Carsten Bormann, Paul Duffy, Kovatsch Matthias, Michael Verschoor, 361 Thomas Watteyne, and Gengyu Wei. 363 7. Change log 365 When published as a RFC, this section needs to be removed. 367 Version 0 to version 1: 369 o Changed patch motivation text. 371 o Removed sub-resource concept. 373 o Updated cache handling. 375 o Extended example. 377 o Update of error handling. 379 Version 1 to version 2 381 o section 3 rephrased use of error 4.09 383 o added conflict handling failure 385 o added idempotent iPATCH method 387 8. References 389 8.1. Normative References 391 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 392 Requirement Levels", BCP 14, RFC 2119, 393 DOI 10.17487/RFC2119, March 1997, 394 . 396 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 397 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 398 Transfer Protocol -- HTTP/1.1", RFC 2616, 399 DOI 10.17487/RFC2616, June 1999, 400 . 402 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 403 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 404 DOI 10.17487/RFC5226, May 2008, 405 . 407 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 408 RFC 5789, DOI 10.17487/RFC5789, March 2010, 409 . 411 [RFC6902] Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object 412 Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902, 413 April 2013, . 415 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 416 Application Protocol (CoAP)", RFC 7252, 417 DOI 10.17487/RFC7252, June 2014, 418 . 420 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 421 DOI 10.17487/RFC7396, October 2014, 422 . 424 8.2. Informative References 426 [I-D.vanderstok-core-comi] 427 Stok, P., Bierman, A., Schoenwaelder, J., and A. Sehgal, 428 "CoAP Management Interface", draft-vanderstok-core-comi-07 429 (work in progress), July 2015. 431 Authors' Addresses 433 Peter van der Stok 434 Consultant 436 Email: consultancy@vanderstok.org 438 Anuj Sehgal 439 Consultant 441 Email: anuj@iurs.org