Simplify change operations using HTTP PATCH

[CarlosRoggan]

The following Blog is about modifying an entity within an SAP Netweaver Gateway OData Service.

The classical way for updating data

Assuming we have a resource in the backend and we wish to modify it, we typically proceed as follows:

1. First, execute a GET request in order to READ the details of an entity.
   In our example, we invoke the following URL, in order to READ the details of a “product”:
   http://<server>:<port>/sap/opu/odata/IWBEP/GWDEMO/ProductCollection('005056A503AC1ED28FC00CB008856AC...)
   Our response body looks like follows:
   
2. In a  second step:
   - copy the relevant content into the request body of a REST client
   - change the value of the property we wish to modify
   - send it as PUT request back to the same URL
   
   In our example, we wish to modify only the "description" of the "product".
   We do so and send the complete xml, including all unchanged properties, to the backend using the HTTP-verb PUT. 
   
   The following screenshot shows such a PUT request (using the Gateway Client)
   
   

Note:

In this Blog, we use the SAP Netweaver Gateway Client (transaction /IWFND/GW_CLIENT) for sending HTTP requests.

One of the many advantages is the button “Use as Request”: it copies the response body to the request body pane.

Let's hesitate a second:

We wonder why we have to send all that stuff if only one property is to be changed...?

The reason is the specification of the HTTP-Verb PUT:

A PUT request indicates a replacement update.

The Gateway Service must replace all property values with those specified in the request body.

Missing properties must be set to their default values.

Missing dynamic properties must be removed or set to NULL.

The simple way

Now, we’d like to introduce a new feature, which comes with SAP Netweaver Gateway 2.0 SP05:

The support for the PATCH operation.

A PATCH request indicates a different update.

The Gateway Service must replace exactly those property values that are specified in the request body.

Missing properties, including dynamic properties, must not be altered.

Note: the HTTP verb PATCH is treated equivalently to MERGE

Now we repeat our example, this time using a PATCH instead of a PUT request.

1. The first step is identical:
   - execute a GET request in order to READ the details of an entity.
2. The second step:
   - we copy only that property we wish to modify from the response to the request body
   - change the value
   - send it as PATCH request  
   
   In our example, the PATCH request looks as follows:
   
   

That’s all.

Just to verify that with a PATCH operation also multiple properties can be modified, have a look at the following screenshot:

Note about service Implementation

For those of you who are implementing Gateway Services in ABAP:

PATCH support is provided with method PATCH_ENTITY of the interface /IWBEP/IF_MGW_APPL_SRV_RUNTIME.

The Gateway Framework provides a basic default implementation of the PATCH_ENTITY method. Prerequisites however are implemented "read" and "update" methods.

The default implementation performs a read before update in order to fetch the complete entity.

The properties of this entity are merged with the property/properties provided within the PATCH request.

At the end, an update_entity is performed.

This default implementation has the side-effect that there’s some overhead, which results in some time loss.  However, these read-before-update calls are done inside the Backend-System (BEP), so no additional communication between Hub and Backend is done. The performance loss is so small that it can be ignored.

On the other hand, the service-creator has the opportunity to increase the performance by providing a custom implementation of this method.

The API Reference can be found in the SAP help:

Developer Guide -> OData Channel -> Advanced Features -> Patch Support

Direct link: http://help.sap.com/saphelp_gateway20sp05/helpdata/en/81/ec4c1e138c4cb09c8b392aab893365/frameset.htm

Note about performance

The duration of a PUT versus a PATCH request can be analyzed and compared using the SAP Netweaver Tracing Tool, which can be started with transaction /IWFND/TRACES.

Find more information about the Trace Tool in the official SAP documentation:

Technical Operations Guide -> Supportability -> Performance Trace

http://help.sap.com/saphelp_gateway20sp05/helpdata/en/9d/da3a2ceca344cf85568ae927e9858d/frameset.htmhttp://help.sap.com/saphelp_gateway20sp05/helpdata/en/56/d0cc05b564411e841141f68294e29f/frameset.htm

With regard to the HTTP communication, the data which is transferred from the client to the Gateway server is much slimmer, which disburdens the load of the HTTP communication.

On the Gateway-side, there’s some overhead of merging the patched properties with the unchanged properties of the entity, before an update is performed.

Thus, we don’t have to wonder that the overall performance of a PATCH is slightly worse than a PUT.

The advantage of the PATCH is the easy handling on the client-side and the thin load of HTTP communication.

The picture below shows a comparison between a PATCH (lines 1 to 12) and a PUT request.

We can see that the duration of the PATCH (883 ms) is slightly higher than the duration of the PUT (819 ms)

We can as well see that– within the PATCH stack - the read and update calls are highlighted in dark blue, which means that they are performed on the Backend-side only.