Calibration Assignment Submission (Patch verb)
The PATCH method is a request method supported by the HTTP protocol for making partial changes to an existing resource.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref> The PATCH method provides an entity containing a list of changes to be applied to the resource requested using the HTTP URI.<ref name="RFC5789"/> The list of changes are supplied in the form of a PATCH document.<ref name="RFC5789"/> If the requested resource does not exist then the Server (computing) may create the resource depending on the PATCH document media type and permissions.<ref name="RFC5789"/> The changes described in the PATCH document must be semantically well defined but can have a different media type than the resource being patched.<ref>Don't Patch Like An Idiot http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/</ref> Frameworks such as XML, JSON can be used in describing the changes in the PATCH document.
PUT vs PATCH vs POST
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, POST and PATCH to create or update resources.<ref name=RFC2616>Hypertext Transfer Protocol -- HTTP/1.1 https://www.ietf.org/rfc/rfc2616.txt</ref>
The main difference between the PUT method 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 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 the PUT method then the PUT method is preferred.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789%7Caccessdate=2015-09-12}}</ref>
The POST method can be used for sending partial updates to a resource. The main difference between the POST method and the PATCH method is that the POST method can only be used 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.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref> <ref>Why PATCH is Good for Your HTTP API https://www.mnot.net/blog/2012/09/05/patch</ref>
Patching resources
The PATCH method is atomic.<ref name="RFC5789"/> Either all the changes specified by the PATCH method are applied or none of the changes are applied by the server.<ref name="RFC5789"/> 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.<ref name="RFC5789"/>
A cached PATCH response is considered stale. It can only be used for the GET and HEAD requests that may follow the PATCH request.<ref name="RFC5789"/>
The entity headers in the PATCH document are only applicable to the PATCH document and cannot be applied to the requested resource.<ref name="RFC5789"/>
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.<ref name="RFC5789"/>
A JSON PATCH document would look like
{ "op": "add", "variable": "count", "value": 1 }
"op" represents the operation performed on the resource. "count" represents the resource being modified. "value" represents the amount being added to the existing resource. <ref name=RFCJSONPATCH>JSON Patch - draft-ietf-appsawg-json-patch-08 https://tools.ietf.org/html/draft-ietf-appsawg-json-patch-08</ref> 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 200 response.
Caution
The PATCH method is not safe. It may create new resources or change resources not mentioned in the URI.<ref name="RFC5789"/>
The PATCH method is not idempotent. It can be made idempotent by using a conditional request.<ref name=RFC5789 />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.<ref name="RFC5789"/>
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 formatted as required.<ref name="RFC5789">PATCH Method for HTTP|url=http://tools.ietf.org/html/rfc5789</ref>
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 informs the client that the PATCH document sent by the client cannot be applied to the requested resource.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref>
Unprocessable 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 because it causes the resource to become invalid or it results in some other error state.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref>
Resource not found
The server returns a 404 (Not Found) response when the PATCH document cannot be applied to a non-existent resource.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref>
Conflicting state
The server returns a 409 (Conflict) response when the server cannot apply a patch for the current state of the resource.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref>
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.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref>
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 is not able to handle concurrent PATCH requests.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref>
Trade-offs between PUT and PATCH
When only a few changes need to be applied to a resource, using the PUT method consumes more bandwidth as compared to the PATCH method which can be used for sending only the changes. 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 work overhead compared to PUT method.<ref name=51elliot>REST API Best Practices 3: Partial Updates - PATCH vs PUT http://51elliot.blogspot.com/2014/05/rest-api-best-practices-3-partial.html</ref> On the other hand, the PUT method requires a GET to be performed before the PUT and it is difficult to ensure that the resource was not modified between the GET and PUT requests.
Security Considerations
The PATCH request needs to use mechanisms such as conditional requests using Etags and the If-Match request header to ensure that data is not corrupted while patching.<ref name=RFC5789 /> In case of a failure of a PATCH request or failure of the channel or a timeout, the client can use a GET request to check the state of the resource.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref> The server has to ensure that malicious clients do not use the PATCH method for consuming excessive server resources.<ref name="RFC5789">PATCH Method for HTTP http://tools.ietf.org/html/rfc5789</ref>
References
<references/>