idnits 2.17.1 draft-ietf-core-etch-04.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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 14, 2016) is 2719 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCthis' is mentioned on line 753, but not defined ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-10 == Outdated reference: A later version (-08) exists of draft-hartke-core-apps-05 == Outdated reference: A later version (-02) exists of draft-snell-search-method-00 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 core P. van der Stok 3 Internet-Draft Consultant 4 Intended status: Standards Track C. Bormann 5 Expires: May 18, 2017 Universitaet Bremen TZI 6 A. Sehgal 7 Consultant 8 November 14, 2016 10 Patch and Fetch Methods for Constrained Application Protocol (CoAP) 11 draft-ietf-core-etch-04 13 Abstract 15 The methods defined in RFC 7252 for the Constrained Application 16 Protocol (CoAP) only allow access to a complete resource, not to 17 parts of a resource. In case of resources with larger or complex 18 data, or in situations where a resource continuity is required, 19 replacing or requesting the whole resource is undesirable. Several 20 applications using CoAP will need to perform partial resource 21 accesses. 23 This specification defines the new CoAP methods, FETCH, PATCH and 24 iPATCH, which are used to access and update parts of a resource. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on May 18, 2017. 43 Copyright Notice 45 Copyright (c) 2016 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. FETCH . . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.2. PATCH and iPATCH . . . . . . . . . . . . . . . . . . . . 4 63 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 4 64 1.4. Terminology and Acronyms . . . . . . . . . . . . . . . . 5 65 2. FETCH Method . . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.1. Response Codes . . . . . . . . . . . . . . . . . . . . . 6 67 2.2. Error Handling . . . . . . . . . . . . . . . . . . . . . 6 68 2.3. Option Numbers . . . . . . . . . . . . . . . . . . . . . 7 69 2.3.1. The Content-Format Option . . . . . . . . . . . . . . 7 70 2.3.2. The ETag Option . . . . . . . . . . . . . . . . . . . 7 71 2.4. Working with Observe . . . . . . . . . . . . . . . . . . 7 72 2.5. Working with Block . . . . . . . . . . . . . . . . . . . 8 73 2.6. Building FETCH Requests . . . . . . . . . . . . . . . . . 8 74 2.7. A Simple Example for FETCH . . . . . . . . . . . . . . . 8 75 3. PATCH and iPATCH Methods . . . . . . . . . . . . . . . . . . 9 76 3.1. Simple Examples for PATCH and iPATCH . . . . . . . . . . 11 77 3.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 13 78 3.3. Option Numbers . . . . . . . . . . . . . . . . . . . . . 13 79 3.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 13 80 4. The New Set of CoAP Methods . . . . . . . . . . . . . . . . . 15 81 5. Security Considerations . . . . . . . . . . . . . . . . . . . 16 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 83 7. Change log . . . . . . . . . . . . . . . . . . . . . . . . . 17 84 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 85 8.1. Normative References . . . . . . . . . . . . . . . . . . 18 86 8.2. Informative References . . . . . . . . . . . . . . . . . 18 87 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 19 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 90 1. Introduction 92 Similar to HTTP, the GET method defined in [RFC7252] for the 93 Constrained Application Protocol (CoAP) only allows the specification 94 of a URI and request parameters in CoAP options, not the transfer of 95 a request payload detailing the request. This leads to some 96 applications to using POST where actually a cacheable, idempotent, 97 safe request is desired. 99 Again similar to the original specification of HTTP, the PUT method 100 defined in [RFC7252] only allows to replace a complete resource. 101 This also leads applications to use POST where actually a cacheable, 102 possibly idempotent request is desired. 104 The present specification adds new CoAP methods: FETCH, to perform 105 the equivalent of a GET with a request body; and the twin methods 106 PATCH and iPATCH, to modify parts of a CoAP resource. 108 1.1. FETCH 110 The CoAP GET method [RFC7252] is used to obtain the representation of 111 a resource, where the resource is specified by a URI and additional 112 request parameters can additionally shape the representation. This 113 has been modelled after the HTTP GET operation and the REST model in 114 general. 116 In HTTP, a resource is often used to search for information, and 117 existing systems varyingly use the HTTP GET and POST methods to 118 perform a search. Often a POST method is used for the sole reason 119 that a larger set of parameters to the search can be supplied in the 120 request body than can comfortably be transferred in the URI with a 121 GET request. The draft [I-D.snell-search-method] proposes a SEARCH 122 method that is similar to GET in most properties but enables sending 123 a request body as with POST. The FETCH method defined in the present 124 specification is inspired by [I-D.snell-search-method], which updates 125 the definition and semantics of the HTTP SEARCH request method 126 previously defined by [RFC5323]. However, there is no intention to 127 limit FETCH to search-type operations, and the resulting properties 128 may not be the same as those of HTTP SEARCH. 130 A major problem with GET is that the information that controls the 131 request needs to be bundled up in some unspecified way into the URI. 132 Using the request body for this information has a number of 133 advantages: 135 o The client can specify a media type (and a content encoding), 136 enabling the server to unambiguously interpret the request 137 parameters in the context of that media type. Also, the request 138 body is not limited by the character set limitations of URIs, 139 enabling a more natural (and more efficient) representation of 140 certain domain-specific parameters. 142 o The request parameters are not limited by the maximum size of the 143 URI. In HTTP, that is a problem as the practical limit for this 144 size varies. In CoAP, another problem is that the block-wise 145 transfer is not available for transferring large URI options in 146 multiple rounds. 148 As an alternative to using GET, many implementations make use of the 149 POST method to perform extended requests, even if they are 150 semantically idempotent, safe, and even cacheable, to be able to pass 151 along the input parameters within the request payload as opposed to 152 using the request URI. 154 The FETCH method provides a solution that spans the gap between the 155 use of GET and POST. As with POST, the input to the FETCH operation 156 is passed along within the payload of the request rather than as part 157 of the request URI. Unlike POST, however the semantics of the FETCH 158 method are more specifically defined. 160 1.2. PATCH and iPATCH 162 PATCH is also specified for HTTP in [RFC5789]. Most of the 163 motivation for PATCH described in [RFC5789] also applies here. iPATCH 164 is the idempotent version of PATCH. 166 The PUT method exists to overwrite a resource with completely new 167 contents, and cannot be used to perform partial changes. When using 168 PUT for partial changes, proxies and caches, and even clients and 169 servers, may get confused as to the result of the operation. PATCH 170 was not adopted in an early design stage of CoAP, however, it has 171 become necessary with the arrival of applications that require 172 partial updates to resources (e.g. [I-D.vanderstok-core-comi]). 173 Using PATCH avoids transferring all data associated with a resource 174 in case of modifications, thereby not burdening the constrained 175 communication medium. 177 This document relies on knowledge of the PATCH specification for HTTP 178 [RFC5789]. This document provides extracts from [RFC5789] to make 179 independent reading possible. 181 1.3. Requirements Language 183 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 184 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 185 "OPTIONAL" in this document are to be interpreted as described in 186 [RFC2119]. 188 1.4. Terminology and Acronyms 190 This document uses terminology defined in [RFC5789] and [RFC7252]. 192 Specifically, it uses the terms "safe" and "idempotent" as defined in 193 Section 5.1 of [RFC7252]. (Further discussion of safe and idempotent 194 methods can now be found in Section 4.2.1 and 4.2.2 of [RFC7231], 195 respectively; the implications of idempotency of methods on server 196 implementations are also discussed in Section 4.5 of [RFC7252].) 198 2. FETCH Method 200 The CoAP FETCH method is used to obtain a representation of a 201 resource, giving a number of request parameters. Unlike the CoAP GET 202 method, which requests that a server return a representation of the 203 resource identified by the effective request URI (as defined by 204 [RFC7252]), the FETCH method is used by a client to ask the server to 205 produce a representation as described by the request parameters 206 (including the request options and the payload) based on the resource 207 specified by the effective request URI. The payload returned in 208 response to a FETCH cannot be assumed to be a complete representation 209 of the resource identified by the effective request URI, i.e., it 210 cannot be used by a cache as a payload to be returned by a GET 211 request. 213 Together with the request options, the body of the request (which may 214 be constructed from multiple payloads using the block protocol 215 [RFC7959]) defines the request parameters. With the FETCH method, 216 implementations may submit a request body of any media type that is 217 defined with the semantics of selecting information from a resource 218 in such a FETCH request; it is outside the scope of this document how 219 information about media types admissible for the specific resource is 220 obtained by the client (although we can hint that form relations 221 ([I-D.hartke-core-apps]) might be a preferred way). It is 222 RECOMMENDED that any discovery method that allows a client to find 223 out that the server supports FETCH also provides information what 224 FETCH payload media types are applicable. 226 FETCH requests are both safe and idempotent with regards to the 227 resource identified by the request URI. That is, the performance of 228 a fetch is not intended to alter the state of the targeted resource. 229 (However, while processing a fetch request, a server can be expected 230 to allocate computing and memory resources or even create additional 231 server resources through which the response to the search can be 232 retrieved.) 234 A successful response to a FETCH request is expected to provide some 235 indication as to the final disposition of the requested operation. 237 If a successful response includes a body payload, the payload is 238 expected to describe the results of the FETCH operation. 240 Depending on the response code as defined by [RFC7252], the response 241 to a FETCH request is cacheable; the request body is part of the 242 cache key. Specifically, 2.05 "Content" response codes, the 243 responses for which are cacheable, are a usual way to respond to a 244 FETCH request. (Note that this aspect differs markedly from 245 [I-D.snell-search-method].) (Note also that caches that cannot use 246 the request payload as part of the cache key will not be able to 247 cache responses to FETCH requests at all.) The Max-Age option in the 248 response has equivalent semantics to its use in a GET. 250 The semantics of the FETCH method change to a "conditional FETCH" if 251 the request message includes an If-Match, or If-None-Match option 252 ([RFC7252]). A conditional FETCH requests that the query be 253 performed only under the circumstances described by the conditional 254 option(s). It is important to note, however, that such conditions 255 are evaluated against the state of the target resource itself as 256 opposed to the results of the FETCH operation. 258 2.1. Response Codes 260 FETCH for CoAP adopts the response codes as specified in sections 5.9 261 and 12.1.2 of [RFC7252] as well as additional response codes 262 mentioned in Section 2.2. 264 2.2. Error Handling 266 A FETCH request may fail under certain known conditions. Beyond the 267 conditions already defined in [RFC7252] for GET, noteworthy ones are: 269 Malformed FETCH payload: If a server determines that the payload 270 provided with a FETCH request is not properly formatted, it can 271 return a 4.00 (Bad Request) CoAP error. The definition of a 272 malformed payload depends upon the CoAP Content-Format specified 273 with the request. 275 Unsupported FETCH payload: In case a client sends a payload that is 276 inappropriate for the resource identified by the Request-URI, the 277 server can return a 4.15 (Unsupported Content-Format) CoAP error. 278 The server can determine if the payload is supported by checking 279 the CoAP Content-Format specified with the request. 281 Unprocessable request: This situation occurs when the payload of a 282 FETCH request is determined as valid, i.e. well-formed and 283 supported, however, the server is unable to or incapable of 284 processing the request. The server can return a 4.22 285 (Unprocessable Entity) CoAP error. In situations when the server 286 has insufficient computing resources to complete the request 287 successfully, it can return a 4.13 (Request Entity Too Large) CoAP 288 error (see also below). In case there are more specific errors 289 that provide more insight into the problem, then those should be 290 used. 292 Request too large: If the payload of the FETCH request is larger 293 than a CoAP server can process, then it can return the 4.13 294 (Request Entity Too Large) CoAP error. 296 It is possible that other error situations, not mentioned here, are 297 encountered by a CoAP server while processing the FETCH request. In 298 these situations other appropriate CoAP status codes can also be 299 returned. 301 2.3. Option Numbers 303 FETCH for CoAP adopts the option numbers as specified in sections 304 5.10 and 12.2 of [RFC7252]. 306 Generally, options defined for GET act in an analogous way for FETCH. 307 Two specific cases are called out in the rest of this section. 309 2.3.1. The Content-Format Option 311 A FETCH request MUST include a Content-Format option (see 312 Section 5.10.3 of [RFC7252]) to specify the media type and content 313 encoding of the request body. (Typically, the media type will 314 specifically have been designed to specify details for a selection or 315 a search on a resource.) 317 2.3.2. The ETag Option 319 The ETag Option on a FETCH result has the same semantics as defined 320 in Section 5.10.6 of [RFC7252]. In particular, its use as a response 321 option describes the "tagged representation", which for FETCH is the 322 same as the "selected representation". The FETCH payload is input to 323 that selection process and therefore needs to be part of the cache 324 key. Similarly, the use of ETag as a request option can elicit a 325 2.03 Valid response if the representation associated with the ETag 326 would still be selected by the FETCH request (including its payload). 328 2.4. Working with Observe 330 The Observe option [RFC7641] can be used with a FETCH request as it 331 can be used with a GET request. 333 2.5. Working with Block 335 The Block1 option [RFC7959] can be used with a FETCH request as it 336 would be used with a POST request; the Block2 option can then be used 337 as with GET or POST. 339 2.6. Building FETCH Requests 341 One property of FETCH that may be non-obvious is that a FETCH request 342 cannot be generated from a link alone, but also needs a way to 343 generate the request payload. Again, form relations 344 ([I-D.hartke-core-apps]) may be able to fill parts of this gap. 346 2.7. A Simple Example for FETCH 348 The FETCH method needs a media type for its payload (as expressed by 349 the Content-Format request option) that specifies the search query in 350 a similar detail as is shown for the patch payload in the PATCH 351 example in Section 3.1. ([I-D.snell-search-method] invents a "text/ 352 query" format based on some hypothetical SQL dialect for its 353 examples.) 355 The example below illustrates retrieval of a subset of a JSON 356 [RFC7159] object (the same object as used in Section 3.1). Using a 357 hypothetical media type "application/example-map-keys+json" (with a 358 Content-Format ID of NNN - not defined as this is just an example), 359 the client specifies the items in the object that it wants: it 360 supplies a JSON array giving the map keys for these items. A 361 resource located at "coap://www.example.com/object" can be 362 represented by a JSON document that we will consider as the target of 363 the FETCH. The client wants to learn the contents of the single map 364 key "foo" within this target: 366 { 367 "x-coord": 256, 368 "y-coord": 45, 369 "foo": ["bar","baz"] 370 } 372 FETCH example: JSON document returned by GET 374 The example FETCH request specifies a single top-level member desired 375 by giving its map key as the sole element of the "example-map-keys" 376 payload: 378 FETCH CoAP://www.example.com/object 379 Content-Format: NNN (application/example-map-keys+json) 380 Accept: application/json 381 [ 382 "foo" 383 ] 385 FETCH example: Request 387 The server returns a subset document with just the selected member: 389 2.05 Content 390 Content-Format: 50 (application/json) 391 { 392 "foo": ["bar","baz"] 393 } 395 FETCH example: Response with subset JSON document 397 By the logic of this example, the requester could have entered more 398 than one map key into the request payload array and would have 399 received a more complete subset of the top-level JSON object that is 400 representing the resource. 402 3. PATCH and iPATCH Methods 404 The PATCH and iPATCH methods request that a set of changes described 405 in the request payload is applied to the target resource of the 406 request. The set of changes is represented in a format identified by 407 a media type. If the Request-URI does not point to an existing 408 resource, the server MAY create a new resource with that URI, 409 depending on the patch document type (whether it can logically modify 410 a null resource) and permissions, as well as other conditions such as 411 the degree of control the server gives clients in creating new 412 entries in its URI space (see also Section 3.4). Creation of a new 413 resource would result in a 2.01 (Created) Response Code dependent on 414 the patch document type. 416 Restrictions to a PATCH or iPATCH request can be made by including 417 the If-Match or If-None-Match options in the request (see 418 Section 5.10.8.1 and 5.10.8.2 of [RFC7252]). If the resource could 419 not be created or modified, then an appropriate Error Response Code 420 SHOULD be sent. 422 The difference between the PUT and PATCH requests is documented in 423 [RFC5789]. When a request is intended to effect a partial update of 424 a given resource, clients cannot use PUT while supplying just the 425 update, but might be able to use PATCH or iPATCH. 427 The PATCH method is not safe and not idempotent, as with the HTTP 428 PATCH method specified in [RFC5789]. 430 The iPATCH method is not safe but idempotent, as with the CoAP PUT 431 method specified in [RFC7252], Section 5.8.3. 433 A client can mark a request as idempotent by using the iPATCH method 434 instead of the PATCH method. This is the only difference between the 435 two. The indication of idempotence may enable the server to keep 436 less state about the interaction; some constrained servers may only 437 implement the iPATCH variant for this reason. 439 PATCH and iPATCH are both atomic. The server MUST apply the entire 440 set of changes atomically and never provide a partially modified 441 representation to a concurrently executed GET request. Given the 442 constrained nature of the servers, most servers will only execute 443 CoAP requests consecutively, thus preventing a concurrent partial 444 overlapping of request modifications. Resuming, modifications MUST 445 NOT be applied to the server state when an error occurs or only a 446 partial execution is possible on the resources present in the server. 448 The atomicity applies to a single server. When a PATCH or iPATCH 449 request is multicast to a set of servers, each server can either 450 execute all required modifications or not. It is not required that 451 all servers execute all modifications or none. An Atomic Commit 452 protocol that provides multiple server atomicity is out of scope. 454 A PATCH or iPATCH response can invalidate a cache as with the PUT 455 response. Caching behaviour as function of the successful (2.xx) 456 response codes for PATCH or iPATCH are: 458 o A 2.01 (Created) response invalidates any cache entry for the 459 resource indicated by the Location-* Options; the payload is a 460 representation of the action result. 462 o A 2.04 (Changed) response invalidates any cache entry for the 463 target resource; the payload is a representation of the action 464 result. 466 There is no guarantee that a resource can be modified with PATCH or 467 iPATCH. Servers MUST ensure that a received PATCH body is 468 appropriate for the type of resource identified by the target 469 resource of the request. 471 It is RECOMMENDED that any discovery method that allows a client to 472 find out that the server supports one of PATCH and iPATCH also 473 provides information what patch payload media types are applicable 474 and which of the two methods are implemented by the server for each 475 of these media types. 477 Servers that do not rely on the idempotency of iPATCH can easily 478 support both PATCH and iPATCH, and it is RECOMMENDED they do so. 479 This is inexpensive to do, as, for iPATCH, there is no requirement on 480 the server to check that the client's intention that the request be 481 idempotent is fulfilled (although there is diagnostic value in that 482 check, so a less-constrained implementation may want to perform it). 484 3.1. Simple Examples for PATCH and iPATCH 486 The example is taken over from [RFC6902], which specifies a JSON 487 notation for PATCH operations. A resource located at 488 coap://www.example.com/object contains a target JSON document. 490 JSON document original state: 491 { 492 "x-coord": 256, 493 "y-coord": 45, 494 "foo": ["bar","baz"] 495 } 497 REQ: iPATCH CoAP://www.example.com/object 498 Content-Format: 51 (application/json-patch+json) 499 [ 500 { "op":"replace", "path":"x-coord", "value":45} 501 ] 503 RET: CoAP 2.04 Changed 505 JSON document final state: 506 { 507 "x-coord": 45, 508 "y-coord": 45, 509 "foo": ["bar","baz"] 510 } 512 This example illustrates use of an idempotent modification to the 513 x-coord member of the existing resource "object". The 2.04 (Changed) 514 response code is conform with the CoAP PUT method. 516 The same example using the Content-Format application/merge- 517 patch+json from [RFC7396] looks like: 519 JSON document original state: 520 { 521 "x-coord": 256, 522 "y-coord": 45, 523 "foo": ["bar","baz"] 524 } 526 REQ: iPATCH CoAP://www.example.com/object 527 Content-Format: 52 (application/merge-patch+json) 528 { "x-coord":45} 530 RET: CoAP 2.04 Changed 532 JSON document final state: 533 { 534 "x-coord": 45, 535 "y-coord": 45, 536 "foo": ["bar","baz"] 537 } 539 The examples show the use of the iPATCH method, but the use of the 540 PATCH method would have led to the same result. Below a non- 541 idempotent modification is shown. Because the action is non- 542 idempotent, iPATCH returns an error, while PATCH executes the action. 544 JSON document original state: 545 { 546 "x-coord": 256, 547 "y-coord": 45, 548 "foo": ["bar","baz"] 549 } 551 REQ: iPATCH CoAP://www.example.com/object 552 Content-Format: 51 (application/json-patch+json) 553 [ 554 { "op":"add","path":"foo/1","value":"bar"} 555 ] 556 RET: CoAP 4.00 Bad Request 557 Diagnostic payload: Patch format not idempotent 559 JSON document final state is unchanged 561 REQ: PATCH CoAP://www.example.com/object 562 Content-Format: 51 (application/json-patch+json) 563 [ 564 { "op":"add","path":"foo/1","value":"bar"} 565 ] 566 RET: CoAP 2.04 Changed 568 JSON document final state: 569 { 570 "x-coord": 45, 571 "y-coord": 45, 572 "foo": ["bar","bar","baz"] 573 } 575 3.2. Response Codes 577 PATCH and iPATCH for CoAP adopt the response codes as specified in 578 sections 5.9 and 12.1.2 of [RFC7252] and add 4.09 "Conflict" and 4.22 579 "Unprocessable Entity" with the semantics specified in Section 3.4 of 580 the present specification. 582 3.3. Option Numbers 584 PATCH and iPATCH for CoAP adopt the option numbers as specified in 585 sections 5.10 and 12.2 of [RFC7252]. 587 3.4. Error Handling 589 A PATCH or iPATCH request may fail under certain known conditions. 590 These situations should be dealt with as expressed below. 592 Malformed PATCH or iPATCH payload: If a server determines that the 593 payload provided with a PATCH or iPATCH request is not properly 594 formatted, it can return a 4.00 (Bad Request) CoAP error. The 595 definition of a malformed payload depends upon the CoAP Content- 596 Format specified with the request. 598 Unsupported PATCH or iPATCH payload: In case a client sends a 599 payload that is inappropriate for the resource identified by the 600 Request-URI, the server can return a 4.15 (Unsupported Content- 601 Format) CoAP error. The server can determine if the payload is 602 supported by checking the CoAP Content-Format specified with the 603 request. 605 Unprocessable request: This situation occurs when the payload of a 606 PATCH request is determined as valid, i.e. well-formed and 607 supported, however, the server is unable to or incapable of 608 processing the request. The server can return a 4.22 609 (Unprocessable Entity) CoAP error. More specific scenarios might 610 include situations when: 612 * the server has insufficient computing resources to complete the 613 request successfully -- 4.13 (Request Entity Too Large) CoAP 614 Response Code (see below), 616 * the resource specified in the request becomes invalid by 617 applying the payload -- 4.09 (Conflict) CoAP Response Code (see 618 below)). 620 In case there are more specific errors that provide more insight 621 into the problem, then those should be used. 623 Resource not found: The 4.04 (Not Found) error should be returned in 624 case the payload of a PATCH request cannot be applied to a non- 625 existent resource. 627 Failed precondition: In case the client uses the conditional If- 628 Match or If-None-Match option to define a precondition for the 629 PATCH request, and that precondition fails, then the server can 630 return the 4.12 (Precondition Failed) CoAP error. 632 Request too large: If the payload of the PATCH request is larger 633 than a CoAP server can process, then it can return the 4.13 634 (Request Entity Too Large) CoAP error. 636 Conflicting state: If the modification specified by a PATCH or 637 iPATCH request causes the resource to enter an inconsistent state 638 that the server cannot resolve, the server can return the 4.09 639 (Conflict) CoAP response. The server SHOULD generate a payload 640 that includes enough information for a user to recognize the 641 source of the conflict. The server MAY return the actual resource 642 state to provide the client with the means to create a new 643 consistent resource state. Such a situation might be encountered 644 when a structural modification is applied to a configuration data- 645 store, but the structures being modified do not exist. 647 Concurrent modification: Resource constrained devices might need to 648 process requests in the order they are received. In case requests 649 are received concurrently to modify the same resource but they 650 cannot be queued, the server can return a 5.03 (Service 651 unavailable) CoAP response code. 653 Conflict handling failure: If the modification implies the 654 reservation of resources or the waiting on conditions to become 655 true, leading to a too long request execution time, the server can 656 return 5.03 (service unavailable) response code. 658 It is possible that other error situations, not mentioned here, are 659 encountered by a CoAP server while processing the PATCH request. In 660 these situations other appropriate CoAP status codes can also be 661 returned. 663 4. The New Set of CoAP Methods 665 Adding three new methods to CoAP's existing four may seem like a 666 major change. However, both FETCH and the two PATCH variants fit 667 well into the REST paradigm and have been anticipated on the HTTP 668 side. Adding both a non-idempotent and an idempotent PATCH variant 669 allows to keep interoperability with HTTP's PATCH method as well as 670 the use/indication of an idempotent PATCH if that is possible, saving 671 significant effort on the server side. 673 Interestingly, the three new methods fit into the old table of 674 methods with a surprising similarity in the idempotence and safety 675 attributes: 677 +------+--------+------+--------+------+------------+ 678 | Code | Name | Code | Name | safe | idempotent | 679 +------+--------+------+--------+------+------------+ 680 | 0.01 | GET | 0.05 | FETCH | yes | yes | 681 | 0.02 | POST | 0.06 | PATCH | no | no | 682 | 0.03 | PUT | 0.07 | iPATCH | no | yes | 683 | 0.04 | DELETE | | | no | yes | 684 +------+--------+------+--------+------+------------+ 686 5. Security Considerations 688 This section analyses the possible threats to the CoAP FETCH and 689 PATCH or iPATCH methods. It is meant to inform protocol and 690 application developers about the security limitations of CoAP FETCH 691 and PATCH or iPATCH as described in this document. 693 The FETCH method is subject to the same general security 694 considerations as all CoAP methods as described in Section 11 of 695 [RFC7252]. Specifically, the security considerations for FETCH are 696 closest to those of GET, except that the FETCH request carries a 697 payload that may need additional protection. The payload of a FETCH 698 request may reveal more detailed information about the specific 699 portions of a resource of interest to the requester than a GET 700 request for the entire resource would; this may mean that 701 confidentiality protection of the request by DTLS or other means is 702 needed for FETCH where it wouldn't be needed for GET. 704 The PATCH and iPATCH methods are subject to the same general security 705 considerations as all CoAP methods as described in Section 11 of 706 [RFC7252]. The specific security considerations for PATCH or iPATCH 707 are nearly identical to the security considerations for PUT 708 ([RFC7252]); the security considerations of Section 5 of [RFC5789] 709 also apply to PATCH and iPATCH. Specifically, there is likely to be 710 a need for authorizing requests (possibly through access control and/ 711 or authentication) and for ensuring that data is not corrupted 712 through transport errors or through accidental overwrites. The 713 mechanisms used for PUT can be used for PATCH or iPATCH as well. 715 The new methods defined in the present specification are secured 716 following the CoAP recommendations for the existing methods as 717 specified in section 9 of [RFC7252]. When additional security 718 techniques are standardized for CoAP (e.g., Object Security), these 719 are then also available for securing the new methods. 721 6. IANA Considerations 723 IANA is requested to add the following entries to the sub-registry 724 "CoAP Method Codes": 726 +------+--------+-----------+ 727 | Code | Name | Reference | 728 +------+--------+-----------+ 729 | 0.05 | FETCH | [RFCthis] | 730 | 0.06 | PATCH | [RFCthis] | 731 | 0.07 | iPATCH | [RFCthis] | 732 +------+--------+-----------+ 734 The FETCH method is idempotent and safe, and it returns the same 735 response codes that GET can return, plus 4.13 (Request Entity Too 736 Large), 4.15 (Unsupported Content-Format), and 4.22 (Unprocessable 737 Entity) with the semantics specified in Section 2.2. 739 The PATCH method is neither idempotent nor safe. It returns the same 740 response codes that POST can return, plus 4.09 (Conflict) and 4.22 741 (Unprocessable Entity) with the semantics specified in Section 3.4. 743 The iPATCH method is identical to the PATCH method, except that it is 744 idempotent. 746 IANA is requested to add the following code to the sub-registry "CoAP 747 response codes": 749 +------+----------------------+-----------+ 750 | Code | Name | Reference | 751 +------+----------------------+-----------+ 752 | 4.09 | Conflict | [RFCthis] | 753 | 4.22 | Unprocessable Entity | [RFCthis] | 754 +------+----------------------+-----------+ 756 IANA is requested to add entries to the sub-registry "CoAP Content- 757 Formats", within the "CoRE Parameters" registry: 759 +------------------------------+----------+----+-----------+ 760 | Media Type | Encoding | ID | Reference | 761 +------------------------------+----------+----+-----------+ 762 | application/json-patch+json | | 51 | [RFC6902] | 763 | application/merge-patch+json | | 52 | [RFC7396] | 764 +------------------------------+----------+----+-----------+ 766 Editors' note (to be removed by RFC editor): RFC 6902 and RFC 7396 767 are not necessary to implement the present specification, not even an 768 option for it. It was just convenient to use the present document to 769 register content-format identifiers for them (and they are used in 770 examples). Therefore, these references are correctly classified as 771 _informative_. 773 7. Change log 775 When published as an RFC, this section needs to be removed. 777 Version 00 is a composition from draft-vanderstok-core-patch-03 and 778 draft-bormann-core-coap-fetch-00 and replaces these two drafts. 780 Version 01 added an example for FETCH and is more explicit about some 781 response codes and options. 783 Version 02 addresses the WGLC comments. 785 Version 03 addresses the IETF last-call comments. 787 8. References 789 8.1. Normative References 791 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 792 Requirement Levels", BCP 14, RFC 2119, 793 DOI 10.17487/RFC2119, March 1997, 794 . 796 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 797 RFC 5789, DOI 10.17487/RFC5789, March 2010, 798 . 800 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 801 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 802 DOI 10.17487/RFC7231, June 2014, 803 . 805 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 806 Application Protocol (CoAP)", RFC 7252, 807 DOI 10.17487/RFC7252, June 2014, 808 . 810 [RFC7641] Hartke, K., "Observing Resources in the Constrained 811 Application Protocol (CoAP)", RFC 7641, 812 DOI 10.17487/RFC7641, September 2015, 813 . 815 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 816 the Constrained Application Protocol (CoAP)", RFC 7959, 817 DOI 10.17487/RFC7959, August 2016, 818 . 820 8.2. Informative References 822 [RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, 823 "Web Distributed Authoring and Versioning (WebDAV) 824 SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, 825 . 827 [RFC6902] Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object 828 Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902, 829 April 2013, . 831 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 832 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 833 2014, . 835 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 836 DOI 10.17487/RFC7396, October 2014, 837 . 839 [I-D.vanderstok-core-comi] 840 Stok, P., Bierman, A., Veillette, M., and A. Pelov, "CoAP 841 Management Interface", draft-vanderstok-core-comi-10 (work 842 in progress), October 2016. 844 [I-D.hartke-core-apps] 845 Hartke, K., "CoRE Application Descriptions", draft-hartke- 846 core-apps-05 (work in progress), October 2016. 848 [I-D.snell-search-method] 849 Reschke, J., Malhotra, A., and J. Snell, "HTTP SEARCH 850 Method", draft-snell-search-method-00 (work in progress), 851 April 2015. 853 Acknowledgements 855 Klaus Hartke has pointed out some essential differences between CoAP 856 and HTTP concerning PATCH, and found a number of problems in an 857 earlier version of Section 2. We are grateful for discussions with 858 Christian Amsuss, Andy Bierman, Timothy Carey, Paul Duffy, Matthias 859 Kovatsch, Michel Veillette, Michael Verschoor, Thomas Watteyne, and 860 Gengyu Wei. Christian Groves provided detailed comments during the 861 Working-Group Last Call, and Christer Holmberg's Gen-ART review 862 provided some further editorial improvement. Further last-call 863 reviews were provided by Sheng Jiang and Phillip Hallam-Baker. As 864 usual, the IESG had some very good reviews, we would like to 865 specifically call out those by Alexey Melnikov (responsible AD) and 866 Alissa Cooper. 868 Authors' Addresses 870 Peter van der Stok 871 Consultant 873 Email: consultancy@vanderstok.org 874 Carsten Bormann 875 Universitaet Bremen TZI 876 Postfach 330440 877 Bremen D-28359 878 Germany 880 Phone: +49-421-218-63921 881 Email: cabo@tzi.org 883 Anuj Sehgal 884 Consultant 886 Email: anuj@iurs.org