In computing, the PATCH method is a request method in

HTTP The Hypertext Transfer Protocol (HTTP) is an application layer protocol in the Internet protocol suite model for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web, w ...

for making partial changes to an existing resource. The PATCH method provides an entity containing a list of changes to be applied to the resource requested using the HTTP

Uniform Resource Identifier A Uniform Resource Identifier (URI) is a unique sequence of characters that identifies a logical or physical resource used by web technologies. URIs may be used to identify anything, including real-world objects, such as people and places, conc ...

(URI). The list of changes are supplied in the form of a PATCH document. If the requested resource does not exist then the

server Server may refer to: Computing * Server (computing), a computer program or a device that provides functionality for other programs or devices, called clients Role * Waiting staff, those who work at a restaurant or a bar attending customers and s ...

may create the resource depending on the PATCH document

media type A media type (also known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the Internet. The Internet Assigned Numbers Authority (IANA) is the official authority for the standardization and publication o ...

and permissions. The changes described in the PATCH document must be semantically well defined but can have a different

than the resource being patched. Languages such as

XML Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing arbitrary data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. T ...

JSON JSON (JavaScript Object Notation, pronounced ; also ) is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays (or other se ...

can be used in describing the changes in the PATCH document.

History of PATCH

As per the semantics defined in the

protocol, the

GET Get or GET may refer to: * Get (animal), the offspring of an animal * Get (divorce document), in Jewish religious law * GET (HTTP), a type of HTTP request * "Get" (song), by the Groggers * Georgia Time, used in the Republic of Georgia * Get AS, a ...

, PUT, and

POST Post or POST commonly refers to: *Mail, the postal system, especially in Commonwealth of Nations countries **An Post, the Irish national postal service **Canada Post, Canadian postal service **Deutsche Post, German postal service ** Iraqi Post, Ir ...

methods need to use a full representation of the resource. The PUT method which can be used for resource creation or replacement is

idempotent Idempotence (, ) is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application. The concept of idempotence arises in a number of p ...

and can be used only for full updates. The edit forms used in conventional

Ruby on Rails Ruby on Rails (simplified as Rails) is a server-side web application framework written in Ruby under the MIT License. Rails is a model–view–controller (MVC) framework, providing default structures for a database, a web service, and web p ...

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.

PUT vs PATCH vs POST

is the foundation of data communication for the

World Wide Web The World Wide Web (WWW), commonly known as the Web, is an information system enabling documents and other web resources to be accessed over the Internet. Documents and downloadable media are made available to the network through web se ...

. It is a request-response protocol which helps users communicate with the server to perform

CRUD In computer programming, create, read, update, and delete (CRUD) are the four basic operations of persistent storage. CRUD is also sometimes used to describe user interface conventions that facilitate viewing, searching, and changing information ...

operations. HTTP defines a number of request methods such as PUT,

and PATCH to create or update resources. The main difference between the PUT and PATCH method is that the PUT method uses the request

URI Uri may refer to: Places * Canton of Uri, a canton in Switzerland * Úri, a village and commune in Hungary * Uri, Iran, a village in East Azerbaijan Province * Uri, Jammu and Kashmir, a town in India * Uri (island), an island off Malakula Isla ...

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 th
PUT
method then th
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.

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 JSON Patch is a web standard format for describing changes in a JSON document. It is meant to be used together with HTTP Patch which allows for the modification of existing HTTP resources. The JSON Patch media type A media type (also known as a ...

document would look like "op" represents the operation performed on the resource. "path" represents the resource being modified. "value" represents the amount being added to the existing resource. 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. A XML PATCH document would look like email='[email protected]' type="@address"> ABC Road The element is located using the 'email' attribute. A new attribute 'address' with the value "ABC Road" is added to the element.

Example

A simple PATCH request example

Host: www.example.com Content-Type: application/example
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: Content-Location: /example.txt ETag: "c0b42b66f" The response 204 means that the request was processed successfully.

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. 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. On the other hand, th
PUT
method requires
GET
to be performed before th
PUT
and it is difficult to ensure that the resource is not modified between th
GET
an
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

. The PATCH method is not

. It can be made

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

The server returns a 400 (Bad request) response if the PATCH document is not formatted as required.

Unsupported patch document

The server returns a 415 (Unsupported

Media Type A media type (also known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the Internet. The Internet Assigned Numbers Authority (IANA) is the official authority for the standardization and publication o ...

) response with an Accept-Patch response header containing supported

s 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

The server returns a 422 (Unprocessable Entity) response when the server understands 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.

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 patch 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 th
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 is not able to handle concurrent PATCH requests.

Security considerations

The PATCH request needs to use mechanisms such as conditional requests using Etags and th
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
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 Hypertext Transfer Protocol