PATCH Method for HTTP
Extracted elements (22)
A new HTTP method is necessary to improve interoperability and prevent errors because PUT is defined to overwrite a resource entirely, and reusing it for partial changes would confuse proxies, caches, clients, and servers. POST is used without broad interoperability for patching because there is no standard way to discover patch format support.
PATCH collisions may be more dangerous than PUT collisions because some patch formats need to operate from a known base-point; applying them to an unexpected state will corrupt the resource rather than simply overwrite it, motivating the conditional-request SHOULD.
The 204 No Content status code is used in successful PATCH responses when no message body is returned. The ETag response header should reflect the entity created by applying the PATCH, and Content-Location should match the Request-URI to indicate the PATCH response body is a resource representation.
There is no single default patch document format that implementations are required to support. Different patch document formats will be appropriate for different types of resources, and no single format is appropriate for all resource types.
When the server does not support a client's patch document format for the identified resource, it SHOULD return a 415 (Unsupported Media Type) response including an Accept-Patch header to inform the client of supported formats.
A cached PATCH response MUST NOT be used to respond to other methods, in particular another PATCH request. It can only be used to respond to subsequent GET and HEAD requests, and only if it contains explicit freshness information and a matching Content-Location header.
Accept-Patch SHOULD appear in the OPTIONS response for any resource that supports the use of the PATCH method. The PATCH method MAY appear in the Allow header even if the Accept-Patch header is absent.
Clients using patch formats that require a known base-point SHOULD use a conditional request such that the request will fail if the resource has been updated since the client last accessed it, for example using a strong ETag in an If-Match header.
Entity-headers contained in the PATCH request apply only to the contained patch document and MUST NOT be applied to the resource being modified. Servers SHOULD NOT store such headers except as trace information.
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale.
Servers MUST ensure that a received patch document is appropriate for the type of resource identified by the Request-URI. There is no single default patch document format that implementations are required to support.
The server MAY create a new resource if the Request-URI does not point to an existing resource, depending on the patch document type (whether it can logically modify a null resource) and permissions.
The server MUST apply the entire set of changes atomically and never provide a partially modified representation. If the entire patch document cannot be successfully applied, the server MUST NOT apply any of the changes.
When the server determines that the patch document is not properly formatted, it SHOULD return a 400 (Bad Request) response. The entity body of error responses SHOULD contain enough information to communicate the nature of the error to the client.
Error handling for PATCH defines specific status codes: 400 for malformed patch documents, 415 for unsupported patch formats, 422 for syntactically valid but unprocessable requests, 404 for resource not found, 409 for conflicting state or concurrent modifications, and 412 for failed preconditions.
The Accept-Patch response header is introduced to specify the patch document formats accepted by the server. Its presence in response to any method is an implicit indication that PATCH is allowed on the resource identified by the Request-URI.
The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The changes are represented in a format called a 'patch document' identified by a media type. PATCH is neither safe nor idempotent as defined by RFC 2616.
The Accept-Patch response header has been added to the permanent message header field registry (RFC 3864). Header field name: Accept-Patch; Applicable Protocol: HTTP; Author/Change controller: IETF.
A document that is patched might be more likely to be corrupted than one overridden in entirety. This risk can be mitigated through conditional requests using ETags and the If-Match header. If a PATCH request fails or no response is received, the client SHOULD issue a GET (bypassing caches) to determine the resource state.
HTTP intermediaries performing virus detection face additional complexity with PATCH because neither the source document nor the patch document may be a virus individually, yet the result could be. This is analogous to risks from byte-range downloads and compressed uploads.
Servers MUST take adequate precautions to ensure that malicious clients cannot consume excessive server resources (e.g., CPU, disk I/O) through the use of PATCH. Authorization and data integrity protections applicable to PUT apply equally to PATCH.
The Accept-Patch header is defined as: Accept-Patch = "Accept-Patch" ":" 1#media-type, specifying a comma-separated listing of media-types with optional parameters as defined in RFC 2616 Section 3.7.