PATCH
The PATCH allows a client to modify a resource according to provided instructions. PATCH is often superior to PUT as semantics of changing a resource are defined by a media type, and multiple non-conflicting changes can be applied at the same time.
Writing requests (clients)
If a client wants to modify a specific part of a resource without overwriting the entire document, it should use the PATCH method with a media type that can express the desired change; if this is available on the server.
Select a media type to use for the patch. It must be a media type that supports patching semantics:
- JSON Patch (
application/json-patch+json
, RFC 6902) - JSON Merge Patch (
application/patch+json
, RFC 7396) - XML Patch (
application/xml-patch+xml
, RFC 7351)
For the request to work, the server must support the selected media type. This is advertised with the Accept-Patch header. If a client is forming a patch but it is not ready to send yet, clients may request this in an OPTIONS request. Clients that already know what to send should pick a client-preferred patch media type and opportunistically send it to the server. If it is not supported, the request should be retried with a supported media type while handling the response status code (see below).
Depending on the round-trip time and payload size, send a Expect: 100-continue header, so that if your choice of patch media type is not supported, you can avoid uploading the entire patch.
Patches may create resources or cause edit conflicts. If applicable, send the request with a conditional test (e.g. If-Match), to avoid creating the resource in the event it does not exist.
Check the error code and follow the error recovery process, if necessary. A 405 (Method Not Allowed), 415 (Unsupported Media Type), or 501 (Not Implemented) status may require that the request be retried with a different media type, or with an equivalent PUT request.
Reading requests (servers)
Determine if the resource exists. If the resource does not exist, and the request allows for the media type to be created (see below), then follow the patch media type semantics for creating the resource. If the resource does exist, apply the patch to the existing resource and commit the changes.
Servers that use 428 (Precondition Required) should judge if the patch media-type has sufficient information to avoid lost updates. If the patch can only be applied if the document is in an expected state, then the server should not require a precondition header, since this would be redundant.
Check the "return" preference for guidance on what response should be generated. By default, return a short document summarizing the changes made.
Applied to non-existent resources
PATCH is allowed to create resources if they do not exist. This behavior may be disabled with If-Match: *
(by making the request conditional on a resource existing), or required with If-None-Match: *
(by making the request conditional on no resource existing). The patch creating the resource must be able to add content from a void or zero-length file, or specify the Content-Type of the resource being created, if there is no way for the server to assume a media type (since the Content-Type of the request is the media type of the patch format, not the resource being created).
Idempotentcy
PATCH is not necessarily idempotent, however it can be with conditional request headers. A resource creating a file may use If-None-Match: *
to ensure that no resource currently exists. Subsequent requests may use If-Match: {etag}
, where {etag} is the ETag value read from a previous request on that resource.
Overview table
- Name
- PATCH
- Description
- Modifies the target resource according to the given instructions.
- Specification
- RFC 5789: PATCH Method for HTTP