RFC 8132

PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)

📅 published April 2017, from ietf

Title Block 📜🎀

Okay bestie, this is RFC 8132 in the Request for Comments series ✨ It's a Standards Track document from the IETF (Internet Engineering Task Force), with ISSN 2070-1721, dated April 2017. The title is PATCH and FETCH Methods for the Constrained Application Protocol (CoAP). It was written by P. van der Stok (Consultant), C. Bormann (Universitaet Bremen TZI), and A. Sehgal (NAVOMI, Inc.) 🫶 The title block doesn't list anything it obsoletes or updates.

Abstract

Okay so the methods in RFC 7252 for CoAP only let you touch a complete resource, never just a piece of it 😭 When a resource is big or complicated, or when it needs to stay continuous, swapping out or requesting the whole thing is just not it 🙈 Lots of CoAP apps need to get at parts of resources.

This spec adds the new CoAP methods FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource 🦋

Status of This Memo

This is an Internet Standards Track document ✨

It's a product of the IETF, so it represents the consensus of the IETF community 🫶 It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 👑 For more about Internet Standards, check Section 2 of RFC 7841. Info about the current status of this document, any errata, and how to give feedback lives at http://www.rfc-editor.org/info/rfc8132 💅

Copyright Notice

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, because they describe your rights and restrictions with respect to this document. Code Components extracted from this document need to include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they are provided without warranty as described in the Simplified BSD License 💜

Table of Contents 🧚

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
  1.1.  FETCH . . . . . . . . . . . . . . . . . . . . . . . . . .   3
  1.2.  PATCH and iPATCH  . . . . . . . . . . . . . . . . . . . .   4
  1.3.  Requirements Language . . . . . . . . . . . . . . . . . .   5
  1.4.  Terminology and Acronyms  . . . . . . . . . . . . . . . .   5
2.  FETCH Method  . . . . . . . . . . . . . . . . . . . . . . . .   5
  2.1.  Response Codes  . . . . . . . . . . . . . . . . . . . . .   6
  2.2.  Error Handling  . . . . . . . . . . . . . . . . . . . . .   6
  2.3.  Option Numbers  . . . . . . . . . . . . . . . . . . . . .   7
    2.3.1.  The Content-Format Option . . . . . . . . . . . . . .   7
    2.3.2.  The ETag Option . . . . . . . . . . . . . . . . . . .   8
  2.4.  Working with Observe  . . . . . . . . . . . . . . . . . .   8
  2.5.  Working with Block  . . . . . . . . . . . . . . . . . . .   8
  2.6.  Building FETCH Requests . . . . . . . . . . . . . . . . .   8
  2.7.  A Simple Example for FETCH  . . . . . . . . . . . . . . .   8
3.  PATCH and iPATCH Methods  . . . . . . . . . . . . . . . . . .   9
  3.1.  Simple Examples for PATCH and iPATCH  . . . . . . . . . .  12
  3.2.  Response Codes  . . . . . . . . . . . . . . . . . . . . .  14
  3.3.  Option Numbers  . . . . . . . . . . . . . . . . . . . . .  14
  3.4.  Error Handling  . . . . . . . . . . . . . . . . . . . . .  15
4.  The New Set of CoAP Methods . . . . . . . . . . . . . . . . .  16
5.  Security Considerations . . . . . . . . . . . . . . . . . . .  17
6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  18
7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  19
  7.1.  Normative References  . . . . . . . . . . . . . . . . . .  19
  7.2.  Informative References  . . . . . . . . . . . . . . . . .  19
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  20
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21

1. Introduction ✨

Similar to HTTP, the GET method defined in [RFC7252] for CoAP only lets you specify a URI and request parameters in CoAP options 🎀 You can't send a request payload that spells out the request. So some apps end up using POST when what they really want is a cacheable, idempotent, safe request 🙈

Again, just like the original HTTP spec, the PUT method defined in [RFC7252] only lets you replace a complete resource. This also pushes apps toward POST when they actually want a cacheable, possibly idempotent request 😭

This spec adds new CoAP methods. FETCH does the equivalent of a GET but with a request body 🦋 Then there are the twin methods, PATCH and iPATCH, which modify parts of a CoAP resource 💖

1.1. FETCH

The CoAP GET method [RFC7252] is used to obtain the representation of a resource. The resource is specified by a URI, and additional request parameters can also shape the representation. This was modeled after the HTTP GET operation and the REST model in general 🧚

In HTTP, a resource is often used to search for information, and existing systems vary in whether they use GET or POST to search. Often POST gets used only so a bigger set of search parameters can ride along in the request body, since they wouldn't comfortably fit in the URI of a GET request 💅 [HTTP-SEARCH] proposes a SEARCH method that's similar to GET in most properties but can send a request body, like POST does. The FETCH method defined here is inspired by [HTTP-SEARCH], which updates the definition and semantics of the HTTP SEARCH request method previously defined by [RFC5323]. However, FETCH isn't limited to search-type operations, and its properties might not match those of HTTP SEARCH 🌸

The big problem with GET is that the information controlling the request has to be crammed into the URI in some unspecified way 😩 Putting that information in the request body has a few perks:

The client can specify a media type (and a content coding), so the server can unambiguously interpret the request parameters in the context of that media type. The request body also isn't limited by the character set restrictions of URIs, which allows a more natural (and more efficient) representation of certain domain-specific parameters ✨
The request parameters aren't limited by the maximum size of the URI. In HTTP, that's a problem because the practical limit on that size varies. In CoAP, another problem is that block-wise transfer isn't available for moving large URI options over multiple rounds 🙈

As an alternative to GET, many implementations use POST for extended requests (even when they're semantically idempotent, safe, and even cacheable), so they can pass the input parameters in the request payload instead of the request URI 🍓

FETCH bridges the gap between GET and POST 🌈 Like POST, the input to the FETCH operation is passed along in the payload of the request rather than as part of the request URI. Unlike POST, though, the semantics of FETCH are defined much more specifically 👑

1.2. PATCH and iPATCH

PATCH is also specified for HTTP in [RFC5789]. Most of the motivation for PATCH described in [RFC5789] applies here too. iPATCH is the idempotent version of PATCH 🦋

PUT exists to overwrite a resource with completely new contents, and it can't be used for partial changes 😭 When people use PUT for partial changes, proxies and caches, and even clients and servers, can get confused about the result of the operation 🙈 PATCH wasn't adopted in an early design stage of CoAP, but it became necessary once apps showed up that need partial updates to resources (for example, [COAP-MGMNT]) 💖 Using PATCH avoids transferring all the data associated with a resource when you only need to modify some of it, so the constrained communication medium doesn't get burdened 🫶

This document relies on knowledge of the PATCH specification for HTTP [RFC5789]. It also provides extracts from [RFC5789] so you can read it independently 🧚

1.3. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] 📖✨

1.4. Terminology and Acronyms

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

Specifically, it uses the terms "safe" and "idempotent" as defined in Section 5.1 of [RFC7252]. (More discussion of safe and idempotent methods can now be found in Sections 4.2.1 and 4.2.2 of [RFC7231], respectively. The implications of method idempotence for server implementations are also discussed in Section 4.5 of [RFC7252].) 🌟

# 2. FETCH Method ✨

okay so the CoAP FETCH method is how a client asks a server to whip up a representation of a resource based on a bunch of request parameters 💅 and this is lowkey different from GET 🫶 with GET, the server just hands back the representation of the resource at the effective request URI (see [RFC7252] for the deets). but with FETCH, the client is like "hey, please produce a representation based on these parameters (the request options AND the payload) using the resource at that effective request URI" 🎀. the payload you get back from a FETCH is NOT guaranteed to be the full representation of the resource 😭 so a cache can't just treat it as the thing to return for a GET. not me almost making that mistake 💀

the request body (which can be built from several payloads using the block protocol in [RFC7959]) plus the request options is what defines the request parameters 🌸. with FETCH, you can send a body of basically any media type that's defined to mean "select some info from a resource" 🦋. how the client figures out which media types the resource accepts is out of scope for this doc, but ngl form relations [CORE-APP] are probably the move 🧚. it is RECOMMENDED that any discovery method that tells a client the server supports FETCH also tells it which FETCH payload media types are okay 💖

FETCH requests are both safe and idempotent with respect to the resource at the request URI 🌈. so running a FETCH is not supposed to change the state of the target resource ✨ (BUT, while the server is processing it, it can totally be expected to use up compute and memory, or even make extra server resources so the search results can be grabbed later 👑).

a successful FETCH response is expected to say what happened with the operation 🔥. if it has a body, that body is expected to describe the results of the FETCH 💜

depending on the response code from [RFC7252], the FETCH response may be cacheable, and the request body is part of the cache key 🍓. specifically, 2.05 (Content) responses (the cacheable ones) are the typical way to answer a FETCH 🎀 (this is a big difference from [HTTP-SEARCH], so don't mix them up 🙈 and caches that can't use the request payload as part of the cache key won't be able to cache FETCH responses at all 😭). the Max-Age option in the response means the same thing it does for GET 🦋

the semantics change to a "conditional FETCH" if the request has an If-Match or If-None-Match option [RFC7252] 👑. a conditional FETCH says "only do this query if the conditions in the option(s) are met" 💅 but here's the tea: those conditions get checked against the state of the target resource itself, NOT the results of the FETCH 🫶

## 2.1. Response Codes

FETCH for CoAP uses the response codes from Sections 5.9 and 12.1.2 of [RFC7252], plus the extra ones in Section 2.2 🌸

## 2.2. Error Handling

a FETCH can fail in certain known situations ✨ beyond the ones already in [RFC7252] for GET, these are the noteworthy ones 💖

<pink>Malformed FETCH payload:</pink> if the server decides the FETCH payload isn't properly formatted, it can send back a 4.00 (Bad Request) CoAP error 💀 what counts as "malformed" depends on the CoAP Content-Format in the request 🧚

<purple>Unsupported FETCH payload:</purple> if the client sends a payload that's not right for the resource at the Request-URI, the server can return a 4.15 (Unsupported Content-Format) CoAP error 🙈 the server figures this out by checking the CoAP Content-Format on the request 🎀

<mint>Unprocessable request:</mint> this is when the FETCH payload is totally valid (well-formed AND supported) but the server can't or isn't capable of processing the request 😭 the server can return a 4.22 (Unprocessable Entity) CoAP error 🫶 and if the server doesn't have enough computing resources to finish it successfully, it can return a 4.13 (Request Entity Too Large) CoAP error instead (more on that below 👀). if there are more specific errors that give extra insight into the problem, those SHOULD be used 💅

wait, I need to be precise here: the original says "those should be used", which is a lowercase "should" and NOT a BCP 14 key word, so no caps needed 🌸

<lavender>Request too large:</lavender> if the FETCH payload is bigger than a CoAP server can handle, it can return the 4.13 (Request Entity Too Large) CoAP error 🐥

it's totally possible for a CoAP server to run into other error situations not listed here while processing a FETCH 🌈 in those cases, other appropriate CoAP response codes can also be returned ✨

## 2.3. Option Numbers

FETCH for CoAP uses the option numbers from Sections 5.10 and 12.2 of [RFC7252] 💖

generally, options defined for GET work in an analogous way for FETCH 🦋 two specific cases get called out in the rest of this section 👑

### 2.3.1. The Content-Format Option

A FETCH request MUST include a Content-Format option (see Section 5.10.3 of [RFC7252]) to specify the media type and content coding of the request body 🫶 (typically, the media type was specifically designed to spell out the details of a selection or search on a resource 🔥)

### 2.3.2. The ETag Option

the ETag option on a FETCH result has the same semantics as in Section 5.10.6 of [RFC7252] 💅 specifically, when it's used as a response option, it describes the "tagged representation", which for FETCH is the same thing as the "selected representation" 🌸 the FETCH payload is the input to that selection process, so it has to be part of the cache key 🧚 similarly, using ETag as a request option can get you a 2.03 (Valid) response if the representation tied to that ETag would still be selected by the FETCH request (payload included) 💜

## 2.4. Working with Observe

the Observe option [RFC7641] can be used with a FETCH request the same way it can with a GET request ✨

## 2.5. Working with Block

the Block1 option [RFC7959] can be used with a FETCH request the way it would be used with a POST request 🎀 and then the Block2 option can be used just like it would be with GET or POST 🌈

## 2.6. Building FETCH Requests

okay, the non-obvious bit 🙈 a FETCH request can't be generated from a link alone 😭 the client also needs a way to generate the request payload 💀 form relations [CORE-APP] might be able to fill that gap too 🦋

## 2.7. A Simple Example for FETCH

the FETCH method needs a media type for its payload (given by the Content-Format request option) that specifies the search query in about as much detail as the PATCH payload in the PATCH example in Section 3.1 💖 ([HTTP-SEARCH] invents a "text/query" format based on a hypothetical SQL dialect for its examples 🧚)

this example shows retrieving a subset of a JSON [RFC7159] object (the same object used in Section 3.1) ✨ using a hypothetical media type "application/example-map-keys+json" (with a Content-Format ID of NNN, which is not defined since this is just an example 🙈), the client lists the items it wants by supplying a JSON array with the map keys for those items 🌸 a resource at <coap://www.example.com/object> can be represented by a JSON document, and we'll treat that as the target of the FETCH 🎀 the client wants to learn the contents of the single map key "foo" inside this target 🫶

{ "x-coord": 256, "y-coord": 45, "foo": ["bar","baz"] }


<rainbow>FETCH Example: JSON Document Returned by GET</rainbow> 🌈

the example FETCH request asks for a single top-level member by putting its map key as the only element of the "example-map-keys" payload 💅

FETCH CoAP://www.example.com/object Content-Format: NNN (application/example-map-keys+json) Accept: application/json [ "foo" ]


<cyan>FETCH Example: Request</cyan> 💖

the server sends back a subset document with just the selected member 🦋

2.05 Content Content-Format: 50 (application/json) { "foo": ["bar","baz"] }


<peach>FETCH Example: Response with Subset JSON Document</peach> 👑

by the logic of this example, the requester could have put more than one map key into the request payload array and would have gotten a more complete subset of the top-level JSON object that represents the resource 🔥✨

3. PATCH and iPATCH Methods ✨

okay bestie, PATCH and iPATCH are the methods that say "please apply this set of changes to the target resource" 💖 The changes ride in the request payload, and a media type tells you what format that payload is in. If the Request-URI doesn't point at an existing resource, the server MAY create a new one at that URI 🦋. Whether it can actually do that depends on the PATCH document type (can it even logically modify a null resource?), on permissions, and on other conditions, like how much control the server gives clients over making new entries in its URI space (see also Section 3.4). If a new resource does get created, the response is a 2.01 (Created) code, depending on the PATCH document type.

Restrictions are possible too. You can add the If-Match or If-None-Match options to the request (see Sections 5.10.8.1 and 5.10.8.2 of [RFC7252]) 🎀. If the resource could not be created or modified, an appropriate error response code SHOULD be sent.

The PUT vs PATCH difference is documented in [RFC5789] 💅. When a request is meant to be a partial update, clients can't use PUT while only supplying the update, but they might be able to use PATCH or iPATCH 🫶.

PATCH is "not safe" and "not idempotent", same as the HTTP PATCH method in [RFC5789]. iPATCH is not safe but idempotent, just like the CoAP PUT method in Section 5.8.3 of [RFC7252] 🌸.

Here's the tea: a client marks a request as idempotent by using iPATCH instead of PATCH, and that's the only difference between them 👑. The idempotence signal can let the server keep less state about the interaction, which is why some constrained servers may only implement iPATCH 🧚.

PATCH and iPATCH are both atomic 😭 The server MUST apply the entire set of changes atomically and never provide a partially modified representation to a concurrently executed GET request. Since these servers are so constrained, most of them will only run CoAP requests one after another, so concurrent partial overlaps of modifications are prevented. In other words, modifications MUST NOT be applied to the server state when an error occurs or when only a partial execution is possible on the resources present in the server.

The atomicity applies to a single server. When a PATCH or iPATCH request is multicast to a set of servers, each server can either execute all required modifications or not. It is not required that all servers execute all modifications or none. An Atomic Commit protocol that provides multiple server atomicity is out of scope 🙈.

A PATCH or iPATCH response can invalidate a cache, kind of like the PUT response does. For the successful (2.xx) response codes, PATCH or iPATCH have this caching behavior:

A 2.01 (Created) response invalidates any cache entry for the resource indicated by the Location-* options; the payload is a representation of the action result.
A 2.04 (Changed) response invalidates any cache entry for the target resource; the payload is a representation of the action result.

There's no guarantee that a resource can be modified with PATCH or iPATCH 💀. Servers MUST ensure that a received PATCH body is appropriate for the type of resource identified by the target resource of the request.

It is RECOMMENDED that any discovery method that lets a client find out the server supports one of PATCH and iPATCH also provides info about which PATCH payload media types are applicable, and which of the two methods the server implements for each of those media types 🌈.

Servers that don't rely on the idempotence of iPATCH can easily support both PATCH and iPATCH, and it is RECOMMENDED that they do so ✨. It's inexpensive to do, because for iPATCH there's no requirement on the server to check that the client's intention for the request to be idempotent is fulfilled (although there is diagnostic value in that check, so a less-constrained implementation may want to perform it).

3.1. Simple Examples for PATCH and iPATCH

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

JSON document original state:

    {
      "x-coord": 256,
      "y-coord": 45,
      "foo": ["bar","baz"]
    }

REQ: iPATCH CoAP://www.example.com/object
Content-Format: 51 (application/json-patch+json)
    [
      { "op":"replace", "path":"x-coord", "value":45}
    ]

RET: CoAP 2.04 Changed

JSON document final state:
    {
      "x-coord": 45,
      "y-coord": 45,
      "foo": ["bar","baz"]
    }

This example shows an idempotent modification to the x-coord member of the existing resource "object" 🦋. The 2.04 (Changed) response code conforms with the CoAP PUT method.

The same example using the Content-Format application/merge-patch+json from [RFC7396] looks like this 👀:

JSON document original state:
    {
      "x-coord": 256,
      "y-coord": 45,
      "foo": ["bar","baz"]
    }

REQ: iPATCH CoAP://www.example.com/object
Content-Format: 52 (application/merge-patch+json)
     { "x-coord":45}

RET: CoAP 2.04 Changed

JSON document final state:
    {
      "x-coord": 45,
      "y-coord": 45,
      "foo": ["bar","baz"]
    }

The examples show the iPATCH method, but using PATCH would have led to the same result 💅. Next up is a non-idempotent modification. Because the action is non-idempotent, iPATCH returns an error, while PATCH executes the action 😭.

JSON document original state:
    {
      "x-coord": 256,
      "y-coord": 45,
      "foo": ["bar","baz"]
    }

REQ: iPATCH CoAP://www.example.com/object
Content-Format: 51 (application/json-patch+json)
    [
      { "op":"add","path":"foo/1","value":"bar"}
    ]
RET: CoAP 4.00 Bad Request
Diagnostic payload: Patch format not idempotent

JSON document final state is unchanged

REQ: PATCH CoAP://www.example.com/object
Content-Format: 51 (application/json-patch+json)
    [
      { "op":"add","path":"foo/1","value":"bar"}
    ]
RET: CoAP 2.04 Changed

JSON document final state:
    {
      "x-coord": 45,
      "y-coord": 45,
      "foo": ["bar","bar","baz"]
    }

3.2. Response Codes

PATCH and iPATCH for CoAP adopt the response codes as specified in Sections 5.9 and 12.1.2 of [RFC7252] and add 4.09 (Conflict) and 4.22 (Unprocessable Entity) with the semantics specified in Section 3.4 of the present specification 🎀.

3.3. Option Numbers

PATCH and iPATCH for CoAP adopt the option numbers as specified in Sections 5.10 and 12.2 of [RFC7252] 🌸.

3.4. Error Handling

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

Malformed PATCH or iPATCH payload: If a server determines that the payload provided with a PATCH or iPATCH request is not properly formatted, it can return a 4.00 (Bad Request) CoAP error. The definition of a malformed payload depends upon the CoAP Content-Format specified with the request.

Unsupported PATCH or iPATCH payload: In case a client sends a payload that is inappropriate for the resource identified by the Request-URI, the server can return a 4.15 (Unsupported Content-Format) CoAP error. The server can determine if the payload is supported by checking the CoAP Content-Format specified with the request.

Unprocessable request: This situation occurs when the payload of a PATCH request is determined to be valid (i.e., well-formed and supported) but the server is unable to or is incapable of processing the request. The server can return a 4.22 (Unprocessable Entity) CoAP error. More specific scenarios might include situations such as:

the server has insufficient computing resources to complete the request successfully -- 4.13 (Request Entity Too Large) CoAP response code (see below); or
the resource specified in the request becomes invalid by applying the payload -- 4.09 (Conflict) CoAP response code (see "Conflicting state" below)).

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

Resource not found: The 4.04 (Not Found) error should be returned if the payload of a PATCH request cannot be applied to a non-existent resource 🙈.

Failed precondition: In case the client uses the conditional If-Match or If-None-Match option to define a precondition for the PATCH request, and that precondition fails, then the server can return the 4.12 (Precondition Failed) CoAP error.

Request too large: If the payload of the PATCH request is larger than a CoAP server can process, then it can return the 4.13 (Request Entity Too Large) CoAP error 🍓.

Conflicting state: If the modification specified by a PATCH or iPATCH request causes the resource to enter an inconsistent state that the server cannot resolve, the server can return the 4.09 (Conflict) CoAP response. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict. The server MAY return the actual resource state to provide the client with the means to create a new consistent resource state. Such a situation might be encountered when a structural modification is applied to a configuration data store but the structures being modified do not exist 💥.

Concurrent modification: Resource-constrained devices might need to process requests in the order they are received. In case requests are received concurrently to modify the same resource but they cannot be queued, the server can return a 5.03 (Service Unavailable) CoAP response code 🧚.

Conflict handling failure: If the modification implies the reservation of resources or the wait time for conditions to become true leads to a too-long request execution time, the server can return a 5.03 (Service Unavailable) response code 😭.

It is possible that other error situations not mentioned here are encountered by a CoAP server while processing the PATCH request. In these situations, other appropriate CoAP status codes can also be returned 🌈.

4. The New Set of CoAP Methods ✨

Okay so adding three new methods to CoAP's existing four might sound like a huge glow-up, but FETCH and the two PATCH variants fit right into the REST vibe, and HTTP already saw them coming 💅. Having both a non-idempotent PATCH and an idempotent one keeps interop with HTTP's PATCH method intact. It also lets you signal an idempotent PATCH when that's possible, which saves the server a ton of work 🫶.

Ngl, the three new methods slot into the old methods table with a surprisingly matching safe and idempotent energy 🦋

+------+--------+------+--------+------+------------+
| Code | Name   | Code | Name   | safe | idempotent |
+------+--------+------+--------+------+------------+
| 0.01 | GET    | 0.05 | FETCH  | yes  | yes        |
| 0.02 | POST   | 0.06 | PATCH  | no   | no         |
| 0.03 | PUT    | 0.07 | iPATCH | no   | yes        |
| 0.04 | DELETE |      |        | no   | yes        |
+------+--------+------+--------+------+------------+

5. Security Considerations 🔐

Let's talk threats 👀 This section looks at the possible security threats to CoAP FETCH and PATCH or iPATCH. It's meant to help protocol and application developers understand the security limitations of CoAP FETCH and PATCH or iPATCH as described in this document.

FETCH is subject to the same general security considerations as all CoAP methods, as described in Section 11 of [RFC7252]. Specifically, FETCH's security stuff is closest to GET's, except that the FETCH request carries a payload that might need extra protection 🔒. The payload of a FETCH request can reveal more detailed info about the specific portions of a resource the requester cares about than a GET for the entire resource would. So confidentiality protection of the request by Datagram Transport Layer Security (DTLS) or other means is needed for FETCH where it wouldn't be needed for GET 💀

PATCH and iPATCH are subject to the same general security considerations as all CoAP methods, as described in Section 11 of [RFC7252]. The specific security considerations for PATCH or iPATCH are nearly identical to the security considerations for PUT [RFC7252]. The security considerations of Section 5 of [RFC5789] also apply to PATCH and iPATCH. Specifically, there is likely to be a need for authorizing requests (possibly through access control and/or authentication) and for ensuring that data is not corrupted through transport errors or through accidental overwrites. The mechanisms used for PUT can be used for PATCH or iPATCH as well 🎀

The new methods defined in the present specification are secured following the CoAP recommendations for the existing methods, as specified in Section 9 of [RFC7252]. When additional security techniques are standardized for CoAP (e.g., Object Security), these techniques are then also available for securing the new methods ✨

6. IANA Considerations 🌸

IANA has added the following entries to the subregistry "CoAP Method Codes":

+------+--------+-----------+
| Code | Name   | Reference |
+------+--------+-----------+
| 0.05 | FETCH  | RFC 8132  |
| 0.06 | PATCH  | RFC 8132  |
| 0.07 | iPATCH | RFC 8132  |
+------+--------+-----------+

The FETCH method is idempotent and safe. It returns the same response codes that GET can return, plus 4.13 (Request Entity Too Large), 4.15 (Unsupported Content-Format), and 4.22 (Unprocessable Entity), with the semantics specified in Section 2.2 👑

The PATCH method is neither idempotent nor safe. It returns the same response codes that POST can return, plus 4.09 (Conflict) and 4.22 (Unprocessable Entity), with the semantics specified in Section 3.4.

The iPATCH method is identical to the PATCH method, except that it is idempotent 🧚

IANA has added the following code to the subregistry "CoAP Response Codes":

+------+----------------------+-----------+
| Code | Name                 | Reference |
+------+----------------------+-----------+
| 4.09 | Conflict             | RFC 8132  |
| 4.22 | Unprocessable Entity | RFC 8132  |
+------+----------------------+-----------+

IANA has added entries to the subregistry "CoAP Content-Formats":

+------------------------------+----------------+----+-----------+
| Media Type                   | Content Coding | ID | Reference |
+------------------------------+----------------+----+-----------+
| application/json-patch+json  | identity       | 51 | [RFC6902] |
| application/merge-patch+json | identity       | 52 | [RFC7396] |
+------------------------------+----------------+----+-----------+

7. References 📚

7.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <http://www.rfc-editor.org/info/rfc2119>.

[RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP",
           RFC 5789, DOI 10.17487/RFC5789, March 2010,
           <http://www.rfc-editor.org/info/rfc5789>.

[RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
           Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
           DOI 10.17487/RFC7231, June 2014,
           <http://www.rfc-editor.org/info/rfc7231>.

[RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
           Application Protocol (CoAP)", RFC 7252,
           DOI 10.17487/RFC7252, June 2014,
           <http://www.rfc-editor.org/info/rfc7252>.

[RFC7641]  Hartke, K., "Observing Resources in the Constrained
           Application Protocol (CoAP)", RFC 7641,
           DOI 10.17487/RFC7641, September 2015,
           <http://www.rfc-editor.org/info/rfc7641>.

[RFC7959]  Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
           the Constrained Application Protocol (CoAP)", RFC 7959,
           DOI 10.17487/RFC7959, August 2016,
           <http://www.rfc-editor.org/info/rfc7959>.

7.2. Informative References

[RFC5323]  Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich,
           "Web Distributed Authoring and Versioning (WebDAV)
           SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008,
           <http://www.rfc-editor.org/info/rfc5323>.

[RFC6902]  Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object
           Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902,
           April 2013, <http://www.rfc-editor.org/info/rfc6902>.

[RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
           Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
           2014, <http://www.rfc-editor.org/info/rfc7159>.

[RFC7396]  Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396,
           DOI 10.17487/RFC7396, October 2014,
           <http://www.rfc-editor.org/info/rfc7396>.

[COAP-MGMNT]
           Stok, P., Bierman, A., Veillette, M., and A. Pelov, "CoAP
           Management Interface", Work in Progress,
           draft-ietf-core-comi-00, January 2017.

[CORE-APP] Hartke, K., "CoRE Application Descriptions", Work in
           Progress, draft-hartke-core-apps-07, February 2017.

[HTTP-SEARCH]
           Reschke, J., Malhotra, A., and J. Snell, "HTTP SEARCH
           Method", Work in Progress, draft-snell-search-method-00,
           April 2015.

Acknowledgements 🫶

Klaus Hartke pointed out some essential differences between CoAP and HTTP concerning PATCH, and found a number of problems in an earlier draft version of Section 2. We're so grateful for discussions with Christian Amsuss, Andy Bierman, Timothy Carey, Paul Duffy, Matthias Kovatsch, Michel Veillette, Michael Verschoor, Thomas Watteyne, and Gengyu Wei. Christian Groves provided detailed comments during the Working Group Last Call, and Christer Holmberg's Gen-ART review provided some further editorial improvement. Further Last Call reviews were provided by Sheng Jiang and Phillip Hallam-Baker. As usual, the IESG had some very good reviews, and we would like to specifically call out those by Alexey Melnikov (responsible AD) and Alissa Cooper 💖

Authors' Addresses

Peter van der Stok
Consultant

Email: consultancy@vanderstok.org


Carsten Bormann
Universitaet Bremen TZI
Postfach 330440
Bremen  D-28359
Germany

Phone: +49-421-218-63921
Email: cabo@tzi.org


Anuj Sehgal
NAVOMI, Inc.

Email: anuj.sehgal@navomi.com

📦 where this page comes from

ietf: rfc8132 2017-04
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms