PATCH (HTTP)
{{Short description|Request method in the HTTP protocol}}
{{HTTP}}
In computing, the PATCH method is a request method in HTTP for making partial changes to an existing resource.{{cite journal|title=PATCH Method for HTTP|year=2010 |doi=10.17487/RFC5789 |url=http://tools.ietf.org/html/rfc5789|accessdate=2015-09-12|last1=Dusseault |first1=L. |last2=Snell |first2=J. |s2cid=42062521 }} The PATCH method provides an entity containing a list of changes to be applied to the resource requested using the HTTP Uniform Resource Identifier (URI). The list of changes are supplied in the form of a PATCH document. If the requested resource does not exist then the server may create the resource depending on the PATCH document media type and permissions. The changes described in the PATCH document must be semantically well defined but can have a different media type than the resource being patched.{{cite web|title=Don't Patch Like An Idiot|url=http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/|website=Don't Patch Like An Idiot|date=14 February 2014 |accessdate=16 September 2015}} Languages such as XML or JSON can be used in describing the changes in the PATCH document.
History of PATCH
As per the semantics defined in the HTTP protocol, the GET, PUT, and POST methods need to use a full representation of the resource. The PUT method which can be used for resource creation or replacement is idempotent and can be used only for full updates. The edit forms used in conventional Ruby on Rails application need to create new resources by applying partial updates to a parent resource. Due to this requirement, the PATCH method was added to the HTTP protocol in 2010.RFC 5789{{cite web|title=History of PATCH|url=http://weblog.rubyonrails.org/2012/2/26/edge-rails-patch-is-the-new-primary-http-method-for-updates/|website=weblog.rubyonrails.org|accessdate=25 September 2015}}
PUT vs PATCH vs POST
HTTP is the foundation of data communication for the World Wide Web. It is a request-response protocol which helps users communicate with the server to perform CRUD operations. HTTP defines a number of request methods such as PUT, POST and PATCH to create or update resources.{{cite web|title=Hypertext Transfer Protocol -- HTTP/1.1|url=https://www.ietf.org/rfc/rfc2616.txt|accessdate=13 September 2015}}
The main difference between the PUT and PATCH method is that the PUT method uses the request URI to supply a modified version of the requested resource which replaces the original version of the resource, whereas the PATCH method supplies a set of instructions to modify the resource. If the PATCH document is larger than the size of the new version of the resource sent by the [https://www.ietf.org/rfc/rfc2616.txt PUT] method then the [https://www.ietf.org/rfc/rfc2616.txt PUT] method is preferred.
The POST method can be used for sending partial updates to a resource. The main difference between the POST and PATCH methods is that the POST method can be used only when it is written to support the applications or the applications support its semantics whereas the PATCH method can be used in a generic way and does not require application support. If the outcome of using the PATCH method is not known then the POST method is preferred.{{cite web|title=Why PATCH is Good for Your HTTP API|url=https://www.mnot.net/blog/2012/09/05/patch|website=Why PATCH is Good for Your HTTP API|accessdate=16 September 2015}}
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. There are many ways of checking whether a patch was applied successfully. For example, the 'diff' utility can be applied to the older version and newer version of a file to find the differences between them.
A cached PATCH response is considered stale. It can only be used for the GET and HEAD requests that may follow the PATCH request.
The entity headers in the PATCH document are only applicable to the PATCH document and cannot be applied to the requested resource.
There is no standard format for the PATCH document and it is different for different types of resources. The server has to check whether the PATCH document received is appropriate for the requested resource.
A JSON Patch document would look like
[
{ "op": "add", "path": "/count", "value": 1 }
]
"op" represents the operation performed on the resource. "path" represents the resource being modified. "value" represents the amount being added to the existing resource.{{cite news|title=JSON Patch - draft-ietf-appsawg-json-patch-08|newspaper=Ietf Datatracker |url=https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-08|accessdate=13 September 2015}} Before applying the changes in the PATCH document, the server has to check whether the PATCH document received is appropriate for the requested resource. If the PATCH request succeeds then it returns a 204 response.{{Cite web|url=https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH|title=PATCH|website=MDN Web Docs|language=en-US|access-date=2018-10-11}}
A XML PATCH document would look like
ABC Road
The element
Example
A simple PATCH request example
{{codett|2=http|PATCH /example.txt HTTP/1.1}}
Host: www.example.com
Content-Type: application/example
[https://msdn.microsoft.com/en-us/library/dd541480.aspx If-Match]: "c0b42b66e"
Content-Length: 120
[Changes: the patch document containing all the changes that need to be made on the resource example.txt]
Successful PATCH response to existing text file:
{{codett|2=http|HTTP/1.1 204 No Content}}
Content-Location: /example.txt
ETag: "dd541480"
The response 204 means that the request was processed successfully.{{Cite web|url=https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH|title=PATCH|website=MDN Web Docs|language=en-US|access-date=2018-10-12}}
Trade-offs between PUT and PATCH
Using the PUT method consumes more bandwidth as compared to the PATCH method when only a few changes need to be applied to a resource.{{Citation needed|reason=Why is it assumed that the comparison with the previous value should be done with the client?|date=May 2018}} But when the PATCH method is used, it usually involves fetching the resource from the server, comparing the original and new files, creating and sending a diff file. On the server side, the server has to read the diff file and make the modifications. This involves a lot of overhead compared to the PUT method.{{cite web|author=Darren|title=REST API Best Practices 3: Partial Updates - PATCH vs PUT|url=http://51elliot.blogspot.com/2014/05/rest-api-best-practices-3-partial.html|website=www.blogger.com|date=7 May 2014 |accessdate=13 September 2015}}
On the other hand, the [https://www.ietf.org/rfc/rfc2616.txt PUT] method requires a [https://www.ietf.org/rfc/rfc2616.txt GET] to be performed before the [https://www.ietf.org/rfc/rfc2616.txt PUT] and it is difficult to ensure that the resource is not modified between the [https://www.ietf.org/rfc/rfc2616.txt GET] and [https://www.ietf.org/rfc/rfc2616.txt PUT] requests.
Caution
The PATCH method is not "safe" in the sense of RFC 2616: it may modify resources, not necessarily limited to those mentioned in the URI.
The PATCH method is not idempotent. It can be made idempotent by using a conditional request. When a client makes a conditional 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.
Error handling
A PATCH request can fail if any of the following errors occur:
=Malformed patch document=
=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 a patch document in a format not implemented by the server. This informs the client that the PATCH document sent by the client cannot be applied to the requested resource.
=Unprocessable request=
=Resource not found=
=Conflicting state=
=Conflicting modification=
The server returns a 412 (Precondition Failed) response when the precondition supplied by the client using the [https://msdn.microsoft.com/en-us/library/dd541480.aspx 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=
Security considerations
The PATCH request needs to use mechanisms such as conditional requests using Etags and the [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match If-Match] request header to ensure that data is not corrupted while patching. In case of a failure of a PATCH request or failure of the channel or a timeout, the client can use a [https://www.ietf.org/rfc/rfc2616.txt GET] request to check the state of the resource. The server has to ensure that malicious clients do not use the PATCH method for consuming excessive server resources.
References
{{reflist}}