The HTTP Patch method is used to request a set of modifications in the request entity to be applied for the resource recognized by the Request-URI. This method plays a vital role in improving interoperability and preventing errors by making partial changes in the resource. The described set of changes are represented in a format identified as Patch Document by media type.
The Patch is a unique method where either all changes requested by the server are applied or none. If a PATCH request is passed using a cache, the Request-URI identifies one or more cached entities. Then the entries are designated as “stale” entries. There is no default format for Patch documentation and servers are required to create a document that fits the needs of the identified resource. This request method should be issued in such a way that it is idempotent as it prevents bad outcomes from the collision of two Patch request on the same resource in a similar time frame .
Patch is very much different as the server processes enclosed entity to modify the resource identified by the Request-URI. The enclosed entity contains a set of instructions that describe the procedure for modifying the current version of the resource existing in origin server. This method affects the resource identified by the Request-URI, and it can also become the cause of possible side effects on other resources.
Example: This example has been taken from RFC 5789. It describes use of Patch Document on an existing resource and the successful response received for the existing text file. In response, 204 code is used due to lack of message body and ETag response header field is used to signify the entity created at http://www.example.com/file.txt by applying Patch.
PATCH /file.txt HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "e0023aa4e" Content-Length: 100
HTTP/1.1 204 No Content Content-Location: /file.txt ETag: "e0023aa4f"
Error Handling in Patch:
A Patch request can fail due to occurrence of any of the mentioned errors.
- Malformed patch document: This error occurs when client sends badly formatted Patch Document. It is specified by 400 (Bad Request) response.
- Unsupported patch document: This error occurs when client sends a Patch document format that is not supported by server for current resource identified by Request URI. It is specified by 415 (Unsupported Media Type) response.
- Unprocessable request: This error occurs when server considers the syntax to be valid and understands the document but is incapable of processing the request. It is specified by 422 (Unprocessable Entity) response.
- Resource not found: This type of error occurs when the Patch document is unable to be applied to a non-existent resource. It is specified by 404 (Not Found) response.
- Conflicting state: This error occurs when request cannot be applied given the state of the resource. It is specified by 409 (Conflict) response.
- Conflicting modification: This error occurs when the client uses If-Match or If-Unmodified-Since header to define a precondition which fails. It is specified by 412 (Precondition Failed) response. When server detects possible conflicting modification and no precondition is defined in the request, then 409 (Conflict) response is sent.
- Concurrent modification: This error occurs when server cannot queue concurrent requests to modify the resource when it is operating under restrictions. It is specified by 409 (Conflict) response. It is specified by 409 (Conflict) Response.