idnits 2.17.1 draft-ietf-core-etch-01.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 (June 24, 2016) is 2861 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 662, but not defined ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-21) exists of draft-ietf-core-block-20 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-09 == Outdated reference: A later version (-08) exists of draft-hartke-core-apps-03 == Outdated reference: A later version (-02) exists of draft-snell-search-method-00 Summary: 1 error (**), 0 flaws (~~), 6 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 Consultant 4 Intended status: Standards Track C. Bormann 5 Expires: December 26, 2016 Universitaet Bremen TZI 6 A. Sehgal 7 Consultant 8 June 24, 2016 10 Patch and Fetch Methods for Constrained Application Protocol (CoAP) 11 draft-ietf-core-etch-01 13 Abstract 15 The existing Constrained Application Protocol (CoAP) methods only 16 allow access to a complete resource. This does not permit 17 applications to access parts of a resource. In case of resources 18 with larger or complex data, or in situations where a resource 19 continuity is required, replacing or requesting the whole resource is 20 undesirable. Several applications using CoAP will need to perform 21 partial resource accesses. 23 Similar to HTTP, the existing Constrained Application Protocol (CoAP) 24 GET method only allows the specification of a URI and request 25 parameters in CoAP options, not the transfer of a request payload 26 detailing the request. This leads to some applications to using POST 27 where actually a cacheable, idempotent, safe request is desired. 29 Again similar to HTTP, the existing Constrained Application Protocol 30 (CoAP) PUT method only allows to replace a complete resource. This 31 also leads applications to use POST where actually a cacheable, 32 possibly idempotent request is desired. 34 This specification adds new CoAP methods, FETCH, to perform the 35 equivalent of a GET with a request body; and the twin methods PATCH 36 and iPATCH, to modify parts of an existing CoAP resource. 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at http://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on December 26, 2016. 55 Copyright Notice 57 Copyright (c) 2016 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (http://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 73 1.1. FETCH . . . . . . . . . . . . . . . . . . . . . . . . . . 3 74 1.2. PATCH and iPATCH . . . . . . . . . . . . . . . . . . . . 4 75 1.3. Requirements Language . . . . . . . . . . . . . . . . . . 4 76 1.4. Terminology and Acronyms . . . . . . . . . . . . . . . . 4 77 2. FETCH Method . . . . . . . . . . . . . . . . . . . . . . . . 5 78 2.1. Response Codes . . . . . . . . . . . . . . . . . . . . . 6 79 2.2. Option Numbers . . . . . . . . . . . . . . . . . . . . . 6 80 2.2.1. The Content-Format Option . . . . . . . . . . . . . . 6 81 2.2.2. The ETag Option . . . . . . . . . . . . . . . . . . . 6 82 2.3. Working with Observe . . . . . . . . . . . . . . . . . . 6 83 2.4. Working with Block . . . . . . . . . . . . . . . . . . . 6 84 2.5. FETCH discussion . . . . . . . . . . . . . . . . . . . . 7 85 2.6. A Simple Example for FETCH . . . . . . . . . . . . . . . 7 86 3. PATCH and iPATCH Methods . . . . . . . . . . . . . . . . . . 8 87 3.1. Simple Examples for PATCH and iPATCH . . . . . . . . . . 9 88 3.2. Response Codes . . . . . . . . . . . . . . . . . . . . . 11 89 3.3. Option Numbers . . . . . . . . . . . . . . . . . . . . . 11 90 3.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 12 91 4. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 13 92 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 93 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 94 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 15 95 8. Change log . . . . . . . . . . . . . . . . . . . . . . . . . 15 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 97 9.1. Normative References . . . . . . . . . . . . . . . . . . 15 98 9.2. Informative References . . . . . . . . . . . . . . . . . 16 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 101 1. Introduction 103 This specification defines the new Constrained Application Protocol 104 (CoAP) [RFC7252] methods, FETCH, PATCH and iPATCH, which are used to 105 access and update parts of a resource. 107 1.1. FETCH 109 The CoAP GET method [RFC7252] is used to obtain the representation of 110 a resource, where the resource is specified by a URI and additional 111 request parameters can additionally shape the representation. This 112 has been modelled after the HTTP GET operation and the REST model in 113 general. 115 In HTTP, a resource is often used to search for information, and 116 existing systems varyingly use the HTTP GET and POST methods to 117 perform a search. Often a POST method is used for the sole reason 118 that a larger set of parameters to the search can be supplied in the 119 request body than can comfortably transferred in the URI with a GET 120 request. The draft [I-D.snell-search-method] proposes a SEARCH 121 method that is similar to GET in most properties but enables sending 122 a request body as with POST. The FETCH method defined in the present 123 specification is inspired by [I-D.snell-search-method], which updates 124 the definition and semantics of the HTTP SEARCH request method 125 previously defined by [RFC5323]. However, there is no intention to 126 limit FETCH to search-type operations, and the resulting properties 127 may not be the same as those of HTTP SEARCH. 129 A major problem with GET is that the information that controls the 130 request needs to be bundled up in some unspecified way into the URI. 131 Using the request body for this information has a number of 132 advantages: 134 o The client can specify a media type (and a content encoding), 135 enabling the server to unambiguously interpret the request 136 parameters in the context of that media type. Also, the request 137 body is not limited by the character set limitations of URIs, 138 enabling a more natural (and more efficient) representation of 139 certain domain-specific parameters. 141 o The request parameters are not limited by the maximum size of the 142 URI. In HTTP, that is a problem as the practical limit for this 143 size varies. In CoAP, another problem is that the block-wise 144 transfer is not available for transferring large URI options in 145 multiple rounds. 147 As an alternative to using GET, many implementations make use of the 148 POST method to perform extended requests, even if they are 149 semantically idempotent, safe, and even cacheable, to be able to pass 150 along the input parameters within the request payload as opposed to 151 using the request URI. 153 The FETCH method provides a solution that spans the gap between the 154 use of GET and POST. As with POST, the input to the FETCH operation 155 is passed along within the payload of the request rather than as part 156 of the request URI. Unlike POST, however the semantics of the FETCH 157 method are more specifically defined. 159 1.2. PATCH and iPATCH 161 PATCH is also specified for HTTP in [RFC5789]. Most of the 162 motivation for PATCH described in [RFC5789] also applies here. iPATCH 163 is the idempotent version of PATCH. 165 The PUT method exists to overwrite a resource with completely new 166 contents, and cannot be used to perform partial changes. When using 167 PUT for partial changes, proxies and caches, and even clients and 168 servers, may get confused as to the result of the operation. PATCH 169 was not adopted in an early design stage of CoAP, however, it has 170 become necessary with the arrival of applications that require 171 partial updates to resources (e.g. [I-D.vanderstok-core-comi]). 172 Using PATCH avoids transferring all data associated with a resource 173 in case of modifications, thereby not burdening the constrained 174 communication medium. 176 This document relies on knowledge of the PATCH specification for HTTP 177 [RFC5789]. This document provides extracts from [RFC5789] to make 178 independent reading possible. 180 1.3. Requirements Language 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 184 "OPTIONAL" in this document are to be interpreted as described in 185 [RFC2119]. 187 1.4. Terminology and Acronyms 189 This document uses terminology defined in [RFC5789] and [RFC7252]. 191 2. FETCH Method 193 The CoAP FETCH method is used to obtain a representation of a 194 resource, giving a number of request parameters. Unlike the CoAP GET 195 method, which requests that a server return a representation of the 196 resource identified by the effective request URI (as defined by 197 [RFC7252]), the FETCH method is used by a client to ask the server to 198 produce a representation as described by the request parameters 199 (including the request options and the payload) based on the resource 200 specified by the effective request URI. The payload returned in 201 response to a FETCH cannot be assumed to be a complete representation 202 of the resource identified by the effective request URI. 204 Together with the request options, the body of the request (which may 205 be constructed from multiple payloads using the block protocol 206 [I-D.ietf-core-block]) defines the request parameters. 207 Implementations MAY use a request body of any content type with the 208 FETCH method; it is outside the scope of this document how 209 information about admissible content types is obtained by the client 210 (although we can hint that form relations ([I-D.hartke-core-apps]) 211 might be a preferred way). 213 FETCH requests are both safe and idempotent with regards to the 214 resource identified by the request URI. That is, the performance of 215 a fetch is not intended to alter the state of the targeted resource. 216 (However, while processing a search request, a server can be expected 217 to allocate computing and memory resources or even create additional 218 server resources through which the response to the search can be 219 retrieved.) 221 A successful response to a FETCH request is expected to provide some 222 indication as to the final disposition of the requested operation. 223 If a successful response includes a body payload, the payload is 224 expected to describe the results of the FETCH operation. 226 Depending on the response code as defined by [RFC7252], the response 227 to a FETCH request is cacheable; the request body is part of the 228 cache key. Specifically, 2.05 "Content" response codes, the 229 responses for which are cacheable, are a usual way to respond to a 230 FETCH request. (Note that this aspect differs markedly from 231 [I-D.snell-search-method].) (Note also that caches that cannot use 232 the request payload as part of the cache key will not be able to 233 cache responses to FETCH requests at all.) The Max-Age option in the 234 response has equivalent semantics to its use in a GET. 236 The semantics of the FETCH method change to a "conditional FETCH" if 237 the request message includes an If-Match, or If-None-Match option 238 ([RFC7252]). A conditional FETCH requests that the query be 239 performed only under the circumstances described by the conditional 240 option(s). It is important to note, however, that such conditions 241 are evaluated against the state of the target resource itself as 242 opposed to the results of the FETCH operation. 244 2.1. Response Codes 246 FETCH for CoAP adopts the response codes as specified in sections 5.9 247 and 12.1.2 of [RFC7252]. 249 2.2. Option Numbers 251 FETCH for CoAP adopts the option numbers as specified in sections 252 5.10 and 12.2 of [RFC7252]. 254 Generally, options defined for GET act in an analogous way for FETCH. 255 Two specific cases are called out in the rest of this section. 257 2.2.1. The Content-Format Option 259 A FETCH request MUST include a Content-Format option to specify the 260 media type and content encoding of the request body. 262 2.2.2. The ETag Option 264 The ETag Option on a FETCH result has the same semantics as defined 265 in Section 5.10.6. of [RFC7252]. In particular, its use as a 266 response option describes the "tagged representation", which for 267 FETCH is the same as the "selected representation". The FETCH 268 payload is input to that selection process and therefore needs to be 269 part of the cache key. Similarly, its use as a request option can 270 elicit a 2.03 Valid response if the representation associated with 271 the ETag would still be selected by the FETCH request (including its 272 payload). 274 2.3. Working with Observe 276 The Observe option [RFC7641] can be used with a FETCH request as it 277 can be used with a GET request. 279 2.4. Working with Block 281 The Block1 option [I-D.ietf-core-block] can be used with a FETCH 282 request as it would be used with a POST request; the Block2 option 283 can then be used as with GET or POST. 285 2.5. FETCH discussion 287 One property of FETCH that may be non-obvious is that a FETCH request 288 cannot be generated from a link alone, but also needs a way to 289 generate the request payload. Again, form relations 290 ([I-D.hartke-core-apps]) may be able to fill parts of this gap. 292 2.6. A Simple Example for FETCH 294 The FETCH method needs a media type for its payload (as expressed by 295 the Content-Format request option) that specifies the search query in 296 a similar detail as is shown for the patch payload in the PATCH 297 example in Section 3.1. ([I-D.snell-search-method] invents a "text/ 298 query" format based on some hypothetical SQL dialect for its 299 examples.) 301 The example below illustrates retrieval of a subset of a JSON object 302 (the same object as used in Section 3.1). Using a hypothetical media 303 type "application/example-map-keys+json", the client specifies the 304 items in the object that it wants: it supplies a JSON array giving 305 the map keys for these items. A resource located at 306 "coap://www.example.com/object" can be represented by a JSON document 307 that we will consider as the target of the FETCH. The client wants 308 to learn the contents of the single map key "foo" within this target: 310 { 311 "x-coord": 256, 312 "y-coord": 45", 313 "foo": ["bar","baz"] 314 } 316 FETCH example: JSON document that might be returned by GET 318 The example FETCH request specifies a single top-level member desired 319 by giving its map key as the sole element of the "example-map-keys" 320 payload: 322 FETCH CoAP://www.example.com/object 323 Content-Format: application/example-map-keys+json 324 Accept: application/json 325 [ 326 "foo" 327 ] 329 FETCH example: Request 331 The server returns a subset document with just the selected member: 333 2.05 Content 334 Content-Format: application/json 335 { 336 "foo": ["bar","baz"] 337 } 339 FETCH example: Response with subset JSON document 341 By the logic of this example, the requester could have entered more 342 than one map key into the request payload array and would have 343 received a more complete subset of the top-level JSON object that is 344 representing the resource. 346 3. PATCH and iPATCH Methods 348 The PATCH and iPATCH methods request that a set of changes described 349 in the request payload is applied to the target resource of the 350 request. The set of changes is represented in a format identified by 351 a media type. If the Request-URI does not point to an existing 352 resource, the server MAY create a new resource with that URI, 353 depending on the patch document type (whether it can logically modify 354 a null resource) and permissions, etc. Creation of a new resource 355 would result in a 2.01 (Created) Response Code dependent of the patch 356 document type. 358 Restrictions to a PATCH or iPATCH request can be made by including 359 the If-Match or If-None-Match options in the request (see 360 Section 5.10.8.1 and 5.10.8.2 of [RFC7252]). If the resource could 361 not be created or modified, then an appropriate Error Response Code 362 SHOULD be sent. 364 The difference between the PUT and PATCH requests is extensively 365 documented in [RFC5789]. 367 The PATCH method is not safe and not idempotent, as with the HTTP 368 PATCH method specified in [RFC5789]. 370 The iPATCH method is not safe but idempotent, as with the CoAP PUT 371 method specified in [RFC7252], Section 5.8.3. 373 A client can mark a request as idempotent by using the iPATCH method 374 instead of the PATCH method. This is the only difference between the 375 two. The indication of idempotence may enable the server to keep 376 less state about the interaction; some constrained servers may only 377 implement the iPATCH variant for this reason. 379 PATCH and iPATCH are both atomic. The server MUST apply the entire 380 set of changes atomically and never provide a partially modified 381 representation to a concurrently executed GET request. Given the 382 constrained nature of the servers, most servers will only execute 383 CoAP requests consecutively, thus preventing a concurrent partial 384 overlapping of request modifications. Resuming, modifications MUST 385 NOT be applied to the server state when an error occurs or only a 386 partial execution is possible on the resources present in the server. 388 The atomicity applies to a single server. When a PATCH or iPATCH 389 request is multicast to a set of servers, each server can either 390 execute all required modifications or not. It is not required that 391 all servers execute all modifications or none. An Atomic Commit 392 protocol that provides multiple server atomicity is out of scope. 394 A PATCH or iPATCH response can invalidate a cache as with the PUT 395 response. Caching behaviour as function of the successful (2.xx) 396 response codes for PATCH or iPATCH are: 398 o A 2.01 (Created) response invalidates any cache entry for the 399 resource indicated by the Location-* Options; the payload is a 400 representation of the action result. 402 o A 2.04 (Changed) response invalidates any cache entry for the 403 target resource; the payload is a representation of the action 404 result. 406 There is no guarantee that a resource can be modified with PATCH or 407 iPATCH. Servers MUST ensure that a received PATCH body is 408 appropriate for the type of resource identified by the target 409 resource of the request. 411 When a request is intended to effect a partial update of a given 412 resource, clients cannot use PUT while supplying just the update, but 413 are free to use PATCH or iPATCH. 415 3.1. Simple Examples for PATCH and iPATCH 417 The example is taken over from [RFC6902], which specifies a JSON 418 notation for PATCH operations. A resource located at 419 coap://www.example.com/object contains a target JSON document. 421 JSON document original state: 422 { 423 "x-coord": 256, 424 "y-coord": 45", 425 "foo": ["bar","baz"] 426 } 428 REQ: iPATCH CoAP://www.example.com/object 429 Content-Format: application/json-patch+json 430 [ 431 { "op":"replace", "path":"x-coord", "value":45} 432 ] 434 RET: CoAP 2.04 Changed 436 JSON document final state: 437 { 438 "x-coord": 45, 439 "y-coord": 45, 440 "foo": ["bar","baz"] 441 } 443 This example illustrates use of an idempotent modification to the 444 x-coord member of the existing resource "object". The 2.04 (Changed) 445 response code is conform with the CoAP PUT method. 447 The same example using the Content-Format application/merge- 448 patch+json from [RFC7396] looks like: 450 JSON document original state: 451 { 452 "x-coord": 256, 453 "y-coord": 45", 454 "foo": ["bar","baz"] 455 } 457 REQ: iPATCH CoAP://www.example.com/object 458 Content-Format: 52 (application/merge-patch+json) 459 { "x-coord":45} 461 RET: CoAP 2.04 Changed 463 JSON document final state: 464 { 465 "x-coord": 45, 466 "y-coord": 45, 467 "foo": ["bar","baz"] 468 } 470 The examples show the use of the iPATCH method, but the use of the 471 PATCH method would have led to the same result. Below a non- 472 idempotent modification is shown. Because the action is non- 473 idempotent, iPATCH returns an error, while PATCH executes the action. 475 JSON document original state: 476 { 477 "x-coord": 256, 478 "y-coord": 45", 479 "foo": ["bar","baz"] 480 } 482 REQ: iPATCH CoAP://www.example.com/object 483 Content-Format: 51 (application/json-patch+json) 484 [ 485 { "op":"add","path":"foo/1","value":"bar"} 486 ] 487 RET: CoAP 4.12 Precondition Failed 489 JSON document final state is unchanged 491 REQ: PATCH CoAP://www.example.com/object 492 Content-Format: 51 (application/json-patch+json) 493 [ 494 { "op":"add","path":"foo/1","value":"bar"} 495 ] 496 RET: CoAP 2.04 Changed 498 JSON document final state: 499 { 500 "x-coord": 45, 501 "y-coord": 45, 502 "foo": ["bar","bar","baz"] 503 } 505 3.2. Response Codes 507 PATCH and iPATCH for CoAP adopt the response codes as specified in 508 sections 5.9 and 12.1.2 of [RFC7252]. 510 3.3. Option Numbers 512 PATCH and iPATCH for CoAP adopt the option numbers as specified in 513 sections 5.10 and 12.2 of [RFC7252]. 515 3.4. Error Handling 517 A PATCH or iPATCH request may fail under certain known conditions. 518 These situations should be dealt with as expressed below. 520 Malformed PATCH or iPATCH payload: If a server determines that the 521 payload provided with a PATCH or iPATCH request is not properly 522 formatted, it can return a 4.00 (Bad Request) CoAP error. The 523 definition of a malformed payload depends upon the CoAP Content- 524 Format specified with the request. 526 Unsupported PATCH or iPATCH payload: In case a client sends payload 527 that is inappropriate for the resource identified by the Request- 528 URI, the server can return a 4.15 (Unsupported Content-Format) 529 CoAP error. The server can determine if the payload is supported 530 by checking the CoAP Content-Format specified with the request. 532 Unprocessable request: This situation occurs when the payload of a 533 PATCH request is determined as valid, i.e. well-formed and 534 supported, however, the server is unable to or incapable of 535 processing the request. The server can return a 4.22 536 (Unprocessable Entity) CoAP error. More specific scenarios might 537 include situations when: 539 * the server has insufficient computing resources to complete the 540 request successfully -- 4.13 (Request Entity Too Large) CoAP 541 Response Code (see below), 543 * the resource specified in the request becomes invalid by 544 applying the payload -- 4.09 (Conflict) CoAP Response Code (see 545 below)), 547 In case there are more specific errors that provide more insight 548 into the problem, then those should be used. 550 Resource not found: The 4.04 (Not Found) error should be returned in 551 case the payload of a PATCH request cannot be applied to a non- 552 existent resource. 554 Failed precondition: In case the client uses the conditional If- 555 Match or If-None-Match option to define a precondition for the 556 PATCH request, and that precondition fails, then the server can 557 return the 4.12 (Precondition Failed) CoAP error. 559 Request too large: If the payload of the PATCH request is larger 560 than a CoAP server can process, then it can return the 4.13 561 (Request Entity Too Large) CoAP error. 563 Conflicting state: If the modification specified by a PATCH or 564 iPATCH request causes the resource to enter an inconsistent state 565 that the server cannot resolve, the server can return the 4.09 566 (Conflict) CoAP response. The server SHOULD generate a payload 567 that includes enough information for a user to recognize the 568 source of the conflict. The server MAY return the actual resource 569 state to provide the client with the means to create a new 570 consistent resource state. Such a situation might be encountered 571 when a structural modification is applied to a configuration data- 572 store, but the structures being modified do not exist. 574 Concurrent modification: Resource constrained devices might need to 575 process requests in the order they are received. In case requests 576 are received concurrently to modify the same resource but they 577 cannot be queued, the server can return a 5.03 (Service 578 unavailable) CoAP response code. 580 Conflict handling failure: If the modification implies the 581 reservation of resources or the waiting on conditions to become 582 true, leading to a too long request execution time, the server can 583 return 5.03 (service unavailable) response code. 585 It is possible that other error situations, not mentioned here, are 586 encountered by a CoAP server while processing the PATCH request. In 587 these situations other appropriate CoAP status codes can also be 588 returned. 590 4. Discussion 592 Adding three new methods to CoAP's existing four may seem like a 593 major change. However, both FETCH and the two PATCH variants fit 594 well into the REST paradigm and have been anticipated on the HTTP 595 side. Adding both a non-idempotent and an idempotent PATCH variant 596 allows to keep interoperability with HTTP's PATCH method as well as 597 the use/indication of an idempotent PATCH if that is possible, saving 598 significant effort on the server side. 600 Interestingly, the three new methods fit into the old table of 601 methods with a surprising similarity in the idempotence and safety 602 attributes: 604 +------+--------+------+--------+------+------------+ 605 | Code | Name | Code | Name | safe | idempotent | 606 +------+--------+------+--------+------+------------+ 607 | 0.01 | GET | 0.05 | FETCH | yes | yes | 608 | 0.02 | POST | 0.06 | PATCH | no | no | 609 | 0.03 | PUT | 0.07 | iPATCH | no | yes | 610 | 0.04 | DELETE | | | no | yes | 611 +------+--------+------+--------+------+------------+ 613 5. Security Considerations 615 This section analyses the possible threats to the CoAP FETCH and 616 PATCH or iPATCH methods. It is meant to inform protocol and 617 application developers about the security limitations of CoAP FETCH 618 and PATCH or iPATCH as described in this document. 620 The FETCH method is subject to the same general security 621 considerations as all CoAP methods as described in [RFC7252]. 623 The security consideration of section 15 of [RFC2616], section 11 of 624 [RFC7252], and section 5 of [RFC5789] also apply. 626 The security considerations for PATCH or iPATCH are nearly identical 627 to the security considerations for PUT ([RFC7252]). The mechanisms 628 used for PUT can be used for PATCH or iPATCH as well. 630 PATCH or iPATCH are secured following the CoAP recommendations as 631 specified in section 9 of [RFC7252]. When additional security 632 techniques are standardized for CoAP, PATCH or iPATCH can also be 633 (and need to be) secured by those new techniques. 635 6. IANA Considerations 637 IANA is requested to add the following entries to the sub-registry 638 "CoAP Method Codes": 640 +------+--------+-----------+ 641 | Code | Name | Reference | 642 +------+--------+-----------+ 643 | 0.05 | FETCH | [RFCthis] | 644 | 0.06 | PATCH | [RFCthis] | 645 | 0.07 | iPATCH | [RFCthis] | 646 +------+--------+-----------+ 648 The FETCH method is idempotent and safe, and it returns the same 649 response codes that GET can return, plus 4.15 "Unsupported Content- 650 Format" with the same semantics as with POST. 652 The PATCH method is neither idempotent nor safe. It returns the same 653 response codes that POST can return, plus 4.09 "Conflict" with the 654 semantics specified in Section 3.4. 656 IANA is requested to add the following code to the sub-registry "CoAP 657 response codes": 659 +------+----------+-----------+ 660 | Code | Name | Reference | 661 +------+----------+-----------+ 662 | 4.09 | Conflict | [RFCthis] | 663 +------+----------+-----------+ 665 IANA is requested to add entries to the sub-registry "CoAP Content- 666 Formats", within the "CoRE Parameters" registry: 668 +------------------------------+----------+----+-----------+ 669 | Media Type | Encoding | ID | Reference | 670 +------------------------------+----------+----+-----------+ 671 | application/json-patch+json | | 51 | [RFC6902] | 672 | application/merge-patch+json | | 52 | [RFC7396] | 673 +------------------------------+----------+----+-----------+ 675 7. Acknowledgements 677 Klaus Hartke has pointed out some essential differences between CoAP 678 and HTTP concerning PATCH, and found a number of problems in an 679 earlier version of Section 2. We are grateful for discussions with 680 Christian Amsuss, Timothy Carey, Paul Duffy, Kovatsch Matthias, 681 Michel Veillette, Michael Verschoor, Thomas Watteyne, and Gengyu Wei. 683 8. Change log 685 When published as a RFC, this section needs to be removed. 687 Version 00 is a composition from draft-vanderstok-core-patch-03 and 688 draft-bormann-core-coap-fetch-00 and replaces these two drafts. 690 9. References 692 9.1. Normative References 694 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 695 Requirement Levels", BCP 14, RFC 2119, 696 DOI 10.17487/RFC2119, March 1997, 697 . 699 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 700 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 701 Transfer Protocol -- HTTP/1.1", RFC 2616, 702 DOI 10.17487/RFC2616, June 1999, 703 . 705 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 706 RFC 5789, DOI 10.17487/RFC5789, March 2010, 707 . 709 [RFC6902] Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object 710 Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902, 711 April 2013, . 713 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 714 Application Protocol (CoAP)", RFC 7252, 715 DOI 10.17487/RFC7252, June 2014, 716 . 718 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 719 DOI 10.17487/RFC7396, October 2014, 720 . 722 [RFC7641] Hartke, K., "Observing Resources in the Constrained 723 Application Protocol (CoAP)", RFC 7641, 724 DOI 10.17487/RFC7641, September 2015, 725 . 727 [I-D.ietf-core-block] 728 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 729 draft-ietf-core-block-20 (work in progress), April 2016. 731 9.2. Informative References 733 [RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, 734 "Web Distributed Authoring and Versioning (WebDAV) 735 SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, 736 . 738 [I-D.vanderstok-core-comi] 739 Stok, P. and A. Bierman, "CoAP Management Interface", 740 draft-vanderstok-core-comi-09 (work in progress), March 741 2016. 743 [I-D.hartke-core-apps] 744 Hartke, K., "CoRE Application Descriptions", draft-hartke- 745 core-apps-03 (work in progress), February 2016. 747 [I-D.snell-search-method] 748 Reschke, J., Malhotra, A., and J. Snell, "HTTP SEARCH 749 Method", draft-snell-search-method-00 (work in progress), 750 April 2015. 752 Authors' Addresses 754 Peter van der Stok 755 Consultant 757 Email: consultancy@vanderstok.org 759 Carsten Bormann 760 Universitaet Bremen TZI 761 Postfach 330440 762 Bremen D-28359 763 Germany 765 Phone: +49-421-218-63921 766 Email: cabo@tzi.org 768 Anuj Sehgal 769 Consultant 771 Email: anuj@iurs.org