PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)
Extracted elements (26)
FETCH bridges the gap between GET and POST: it allows passing query parameters in the request body (like POST) while retaining safe and idempotent semantics. This enables cacheable, server-side selection of resource subsets without the URI size limitations and character set constraints that GET would impose.
iPATCH (idempotent PATCH) was introduced as a distinct method so that constrained servers can implement only one variant, saving state required to handle non-idempotent PATCH. The indication of idempotence enables servers to keep less state about the interaction.
PATCH atomicity on a single server does not extend to multicast scenarios: each server executes all or no modifications independently, and an Atomic Commit protocol providing multi-server atomicity is explicitly out of scope.
The three new methods (FETCH, PATCH, iPATCH) align with existing CoAP methods by matching their idempotence and safety attributes: FETCH mirrors GET (safe+idempotent, code 0.05), PATCH mirrors POST (neither, code 0.06), and iPATCH mirrors PUT (idempotent, code 0.07).
A FETCH request cannot be generated from a link alone; the client also needs a way to generate the request payload. Form relations (CORE-APP) may fill parts of this gap.
The Block1 option (RFC 7959) can be used with a FETCH request as it would be used with a POST request; the Block2 option can be used as it would with GET or POST.
The Observe option (RFC 7641) can be used with a FETCH request as it can be used with a GET request.
A FETCH request MUST include a Content-Format option to specify the media type and content coding of the request body.
FETCH requests are both safe and idempotent with regards to the resource identified by the request URI; the performance of a FETCH is not intended to alter the state of the targeted resource.
If the resource could not be created or modified by a PATCH or iPATCH request, then an appropriate error response code SHOULD be sent.
It is RECOMMENDED that any discovery method that allows a client to find out that the server supports PATCH or iPATCH also provide information regarding what PATCH payload media types are applicable and which methods are implemented for each media type.
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. Modifications MUST NOT be applied when an error occurs or only partial execution is possible.
Servers MUST ensure that a received PATCH body is appropriate for the type of resource identified by the target resource of the request.
When a conflicting-state error occurs, 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 the means to create a new consistent state.
Additional error codes for PATCH/iPATCH beyond FETCH errors: 4.04 (Not Found) if PATCH cannot apply to a non-existent resource, 4.12 (Precondition Failed) for failed If-Match/If-None-Match conditions, 4.09 (Conflict) for modifications causing inconsistent resource state, and 5.03 (Service Unavailable) for concurrent modification conflicts.
Depending on the response code, the response to a FETCH request is cacheable; the request body is part of the cache key. A 2.05 (Content) response is the typical cacheable response for FETCH. The Max-Age option in the response has equivalent semantics to its use in a GET.
Error codes for FETCH: 4.00 (Bad Request) for malformed payload, 4.15 (Unsupported Content-Format) for inappropriate payload, 4.22 (Unprocessable Entity) for valid but unprocessable payload, and 4.13 (Request Entity Too Large) when payload exceeds server capacity.
PATCH cache invalidation: a 2.01 (Created) response invalidates any cache entry for the resource indicated by Location-* options; a 2.04 (Changed) response invalidates any cache entry for the target resource. Both carry the action result as payload.
The FETCH method requests that a server produce a representation as described by the request parameters (including options and payload) based on the resource specified by the effective request URI. Unlike GET, the FETCH payload is part of the cache key and the response cannot be assumed to be a complete representation of the resource.
The PATCH and iPATCH methods request that a set of changes described in the request payload be applied to the target resource. If the Request-URI does not point to an existing resource, the server MAY create a new resource, resulting in a 2.01 (Created) response.
The semantics of FETCH change to a 'conditional FETCH' if the request includes If-Match or If-None-Match options; such conditions are evaluated against the state of the target resource, not the results of the FETCH operation.
Three new entries added to the IANA 'CoAP Method Codes' subregistry: code 0.05 FETCH (safe, idempotent), code 0.06 PATCH (not safe, not idempotent), and code 0.07 iPATCH (not safe, idempotent), all referencing RFC 8132.
Two new entries added to the IANA 'CoAP Content-Formats' subregistry: application/json-patch+json (identity, ID 51, RFC 6902) and application/merge-patch+json (identity, ID 52, RFC 7396).
PATCH and iPATCH security considerations are nearly identical to PUT (RFC 7252) and HTTP PATCH (RFC 5789): there is likely a need for authorizing requests through access control and/or authentication and for ensuring data integrity against transport errors and accidental overwrites.
The FETCH request payload may reveal more detailed information about specific portions of a resource than a GET for the entire resource; this may require confidentiality protection via DTLS or other means even when GET would not need it.
The new methods are secured following CoAP recommendations for existing methods (Section 9 of RFC 7252). When additional security techniques are standardized for CoAP (e.g., Object Security), those techniques are also available for securing FETCH, PATCH, and iPATCH.