PI REST Adapter - Define custom http header elements

[alex_bundschuh]

This blog is part of a collection of blog entries that shows architectural concepts and configuration of the SAP PI REST Adapter. We also added some sample scenarios to make it easier for you to understand how your scenario can be implemented using the PI REST Adapter.

If you haven’t done so far, best is to start with the very first blog PI Rest Adapter - Don't be afraid within the blog series covering the concepts of the REST adapter. A complete list of all blog entries can be accessed from here PI REST Adapter - Blog Overview.

With release 7.31 SP15 / 7.4 SP10 we have enhanced the REST adapter supporting custom header elements. In the receiver REST channel, you can define your own header elements which are added to the http header of the service request.

Scenario

For versioning REST APIs, there are two approaches which are commonly used and which are well documented on the net, either via URI versioning or via media type versioning. For former, you put the version number into the URI of the service request, e.g., http://host:port/rest/v2/query/customer/67. For latter, you define the version of the resource representation which you provide or which you expect when consuming a RESTful service using the http headers Content-type or Accept. Here, you define your own vendor-specific media type which may hold information about resource type, version, and format, e.g., application/vnd.mycompany.myapp.customer-v2+json.

I have enhanced the scenario from the previous blog PI REST Adapter - Custom error handling in order to handle versions. The figure below shows the Integration Flow from SOAP to REST which calls a RESTful service to gather customer information. The RESTful service provides two versions. In version 1, the information returned to us contains the customer name and its address. In version 2, contact information has been added. We use GET operation and the http header element Accept to pass the version to the service provider.

In the following, I show you how the receiver channel of adapter type REST has been maintained. I focus here on the settings which are needed to set the http header.

Configuring the REST receiver channel

In the SAP Process Integration Designer perspective of the NetWeaver Developer Studio (NWDS), open the Integration Flow, double-click on the receiver channel of type REST, and switch to the REST URL tab below the Adapter-Specific tab. Maintain the target URL of the RESTful service. The version in the http header should be dynamically set based on the version provided in the payload of the service request. Hence, we need to define a variable that holds the version number. Add a new pattern variable replacement. As the value source choose XPath Expression from the drop down menu. Maintain the variable name and the xpath expression, here version_part and //version.

Switch to tab HTTP Headers, and add a new entry with header name Accept and value pattern application/vnd.mycompany.myapp.customer-{version_part}+json. Note, that we use the beforehand maintained variable version_part in curly brackets which will be replaced with the actual version number during runtime.

Running the scenario

For testing the scenario, you can use soapui. I first ran the scenario with version v1. In the response you can see that the version 1 of the RESTful service was called returning name and address only.



In the audit log in message monitoring, the REST adapter added an entry indicating that the header Accept was set acordingly.



When running the scenario with version v2, version 2 of the RESTful service was called returning name, address, and contact, as can be seen from the payload of the response below. By the way, whenever the data format is JSON, the original payload in JSON format is logged before being converted into XML format. This small feature has been shipped with 7.31 SP15 / 7.4 SP10 as well.



 

I hope this blog was helpful to understand how custom headers can be defined. If you like to learn more, check out the other blogs in the series, accessible from the main blog PI REST Adapter - Blog Overview.