User:Saravanan Balasubramanian/sandbox

The PATCH method is a request method supported by the HTTP protocol for making partial changes to a resource. The PATCH method specifies a set of changes to be made to the resource requested using the HTTP URI. The set of changes are supplied in the form of a JSON PATCH document. If the requested resource does not exist then the server may create the resource if the PATCH document has the permissions for creating the resource.

PUT vs PATCH

HTTP is the foundation of data communication for the World Wide Web. HTTP is a request-response protocol which helps users to communicate with the server to perform CRUD operations. HTTP supports a number of request methods such as PUT, GET, POST, DELETE and PATCH which are used to perform CRUD operations on the server.

The main difference between the PUT method and PATCH method is that the PUT method supplies the modified version of the requested resource in the request URI which replaces the original version of the requested resource whereas the PATCH method supplies a set of instructions to modify the requested resource. If the PATCH document is larger than the size of the new version of the resource sent by PUT method then it is advisable to use the PUT method.If the PATCH document does not modify the requested resource in predictable ways then it is advisable to use the POST method.

Patching Resources

The PATCH method is atomic. Either all the changes specified by the PATCH method are applied or none of the changes are applied by the server.

A cached PATCH response is considered stale. The entity headers in the PATCH document are only applicable to the PATCH document and cannot be applied to the requested resource.

A JSON PATCH document would look like

{ "op": "replace", "path": "/1/email_id", "value": jsonpatch@example.com}

Op, which represents the operation performed on the resource, must be one of "add","remove", "replace", "move", "copy" or "test". Path and value represent the path of the resource and the new value of the resource respectively. The server has to check whether the PATCH document received is appropriate for the requested resource.

The server can add the PATCH method to the list of allowed methods in the ALLOW header in the OPTIONS response indicating that it supports the PATCH method. The OPTIONS response may optionally include the ACCEPT-PATCH header which is used to specify the PATCH document formats supported by the server.

Caution

The PATCH method may create new resources or change resources not mentioned in the URI. Hence, the PATCH method is not safe.

The PATCH method can be made idempotent by using a conditional request. When a client makes a request to a resource, the request succeeds only if the resource has not been updated since the client last accessed that resource. This also helps in preventing corruption of the resource since some updates to a resource can only be performed starting from a certain base point. The checking need not be performed if the updates do not need a certain base point.

Error Handling

A PATCH request can fail if any of the following errors occur: Malformed patch document The server returns a 400 (Bad request) response if the PATCH document is not properly formatted.

Unsupported patch document The server returns a 415 (Unsupported Media Type) response with an Accept-Patch response header containing supported media types when the client sends an unsupported patch document. This notifies the client that the PATCH document sent by the client cannot be applied to the requested resource.

Un-processable request The server returns a 422(Unprocessable Entity) response when the server is able to understand the PATCH document but is unable to modify the requested resource either becuase it causes the resource to become invalid or results in some other error state.

Resource not found The server returns a 404(Not found) response when the PATCH document cannot be applied to a non-existent resource.

Conflicting state The server returns a 409(Conflict) response when the server cannot apply a modification for the current state of the resource.

Conflicting modification The server returns a 412(Precondition Failed) response when the precondition supplied by the client using the If-Match or If-Unmodified-Since header fails. If no precondition is supplied and there is a conflicting modification then the server returns a 409(Conflict) response.

Concurrent modification The server returns a 409(Conflict) response if the PATCH requests to a certain resource need to be applied in a certain order and the server receives concurrent requests but is unable to queue them.

Example

A Simple PATCH Example

  PATCH /file.txt HTTP/1.1
  Host: www.example.com
  Content-Type: application/example
  If-Match: "e0023aa4e"
  Content-Length: 100
  [description of changes]

This example illustrates use of a hypothetical patch document on an existing resource.

Successful PATCH response to existing text file:

  HTTP/1.1 204 No Content
  Content-Location: /file.txt
  ETag: "e0023aa4f"

  The 204 response code is used because the response does not carry a
  message body (which a response with the 200 code would have).  Note
  that other success codes could be used as well. -{RFC}
 

Advantages and Disadvantages

Since the PATCH method only specifies the changes that need to be made to a resource it requires less bandwidth. But when the PATCH method is used, it usually involves fetching the resource from the server, comparing the original and new files and creating a diff file. On the server side,the server has to read the diff file and make the modifications. This involves a lot of work overhead compared to PUT method.

Security Considerations

The PATCH request must use access control and ensure that data is not corrupted by using mechanisms such as conditional requests using Etags and the If-Match request header. In case if the PATCH request fails or if the channel fails or a timeout occurs before the client receives a response then the client can issue a GET request to check the state of the resource. Also, the server must ensure that malicious clients do not use the PATCH method for consuming excessive server resources.