2.2.4.1 PATCH/MERGE

Data services support two types of update operations: merge and replace. In accordance with [RFC5023] and as described in Update Request Types (section 2.2.7.3), the HTTP PUT method specifies that an update operation MUST be carried out by using replace semantics.

PATCH is an HTTP verb defined by [RFC5789] and is supported only in the OData 3.0 protocol. The semantics of the method for use in this protocol are as defined by [RFC5789], except where explicitly noted in this document.

Note that this protocol does not define the semantics for the OPTIONS request method that is defined in [RFC5789].

The remainder of this section defines a custom HTTP MERGE method that is used in the OData 1.0 and OData 2.0 protocols to specify that an update is to be completed by using merge semantics. All the directives defined for the PUT method in HTTP, as specified in [RFC2616], and AtomPub, as specified in [RFC5023], apply equally to the HTTP MERGE method. The only difference between an HTTP request that uses MERGE or PATCH and PUT is client intent.

Since MERGE is not one of the verbs that is defined in the HTTP specification [RFC2616], using the MERGE verb might not flow through network intermediaries as seamlessly as methods that are defined in the HTTP specification. The HTTP PATCH verb is preferred over HTTP MERGE when working with data services that support the OData 3.0 protocol. Data services that support the OData 2.0 and OData 3.0 protocols can support verb tunneling to mitigate this limitation, as defined in Tunneled Requests (section 2.2.7.7).

The semantics of a MERGE request on a data service entity is to merge the content in the request payload with the entity's current state. The merging is done by comparing each component (that is, each individual primitive-valued or collection-valued property of the entity or complex type) within the request body to the entity as it exists on the server.

If a component in the request body is not defined on the entity that is to be updated, the request MAY be considered malformed.

If a component in the request body does match a component on the entity that is to be updated, the value of the component in the request body MUST replace the matching component of the entity to be updated and the matching process continues with the children of the component from the request body.

The ABNF syntax of the HTTP MERGE method is defined as follows.

 Method = "MERGE"    ; see [RFC2616] section 5.1.1

Listing: ABNF Grammar for HTTP MERGE Method