Update of selected properties using PATCH

[Former Member]

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:

1. There is an UPDATE method defined for the relevant entity - this method still needs to be called by the OData handler.
2. No locking is required.
3. 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.