We are all familiar with the HTTP verbs POST and PUT which are used to create and update entities, but there is another verb at our disposal - PATCH.
When an update is carried out using PUT, you must supply a body that represents the entire changed property set; that is, you need to GET the entity, change the property (or several) that you wish to update and then put all properties back with a PUT request.
A PATCH request is a merge operation and only needs to be given the properties that are changed, which is useful. Assume you know an entity has a 'Price' property and you wish to change it; all you need to know in addition to the property name is the entity key. Then issue a PATCH request, which is in the same form as a PUT except the full property set does not need to be in the content.
Example: simple price change
1 - POST a new entity
<entry xmlns=http://www.w3.org/2005/Atom xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
<content type="application/xml">
<m:properties>
<d:FooID></d:FooID>
<d:Currency>GBP</d:Currency>
<d:Price>150.59</d:Price>
<d:Category>M</d:Category>
<d:Foonumber>90031</d:Foonumber>
<d:Name>Post32</d:Name>
</m:properties>
</content>
</entry>
New entry has the key "foos(binary'005056A307981ED2BEB93B640CF48EF8')"
2 - PATCH to that key with a new Price value.
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
<content type="application/xml">
<m:properties>
<d:Price>199.99</d:Price>
</m:properties>
</content>
</entry>
(a PUT would look like this:)
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
<content type="application/xml">
<m:properties>
<d:FooID>AFBWoweYHtK+uTtkDPSO+A==</d:FooID>
<d:Currency>GBP</d:Currency>
<d:Price>199.95</d:Price>
<d:Category>M</d:Category>
<d:Foonumber>90001</d:Foonumber>
<d:Name>Post31</d:Name>
</m:properties>
</content>
</entry>
3 - GET the updated entity to check.
<m:properties>
<d:FooID>AFBWoweYHtK+uTtkDPSO+A==</d:FooID>
<d:Currency>GBP</d:Currency>
<d:Price>199.95</d:Price>
<d:Category>M</d:Category>
<d:Foonumber>90001</d:Foonumber>
<d:Name>Post31</d:Name>
</m:properties>
The use of PATCH does not require any additional coding in the DPC class; it will work out-of-the-box assuming that:
- There is an UPDATE method defined for the relevant entity - this method still needs to be called by the OData handler.
- No locking is required.
- The entity instance actually exists.
It is also important to NOT send any empty property values unless they are intended to be cleared, i.e. do not take a feed and simply empty the properties before patching.
All DPC extension classes within later SP releases contain an inherited PATCH handler - /IWBEP/IF_MGW_APPL_SRV_RUNTIME~PATCH_ENTITY. This is a generic handler which will merge the current entity state with your changed state and apply it using the entity-specific UPDATE method. You won't find a generated PATCH method per entity like UPDATE and CREATE.
If you require a locking mechanism (it's recommended!), the default implementation has a commented section at the end which provides a template for doing so.
