Skip to Content
Technical Articles

PI REST Adapter – Define custom http header elements

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.


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.

01 iflow.png

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.

07 channel config rest url.png

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.

08 channel config http headers.png

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.

02 soapui v1.png

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

06 msg moni ausit log v1.png

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.

03 msg version v2.png


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.

You must be Logged on to comment or reply to a post.
  • Hi Alexander,

    We are in PI 7.4 SP 10 patch 000 and NWDS 7.31 SP15

    I could not able to view the HTTP Headers and Error Handling tab in Integration Directory or NWDS for the REST adapters , Could you please let me know if there are any corrections/patch for this to be seen in the REST Adapters.

    We wanted to use REST adpater to connect to SFDC applications in our project.



  • Thanks Alex,

    We were missing that update for Adapter metedata, its fixed now.

    One more query need to know if SAP has provided any document for OAuthBean for REST adapters .

    I could see below paraments in path localejbs/OAuthBean : :


      private static final String OAUTH_ACCESS_TOKEN_URL = "accessTokenUrl";

      private static final String OAUTH_FLOW = "flow";

      private static final String OAUTH_SAML_ISSUER = "samlIssuer";

      private static final String OAUTH_SAML_AUDIENCE = "samlAudience";

      private static final String OAUTH_SAML_RECIPIENT = "samlRecipient";

      private static final String OAUTH_SAML_SUBJECT = "samlSubject";

      private static final String OAUTH_SAML_SIG_KEYSTORE = "samlSigKeystore";

      private static final String OAUTH_SAML_SIG_KEYALIAS = "samlSigKeyalias";

      private static final String OAUTH_ACCESS_TOKEN_REQUEST_PREFIX = "accessTokenRequest_";

      private static final String OAUTH_HTTP_PROXY_HOST = "httpProxyHost";

      private static final String OAUTH_HTTP_PROXY_PORT = "httpProxyPort";

      private static final String OAUTH_HTTP_PROXY_USER = "httpProxyUser";

      private static final String OAUTH_HTTP_PROXY_PASS = "httpProxyPass";

      private static final String OAUTH_ATTRIBUTE_NAMESPACE = "xiAttributeNamespace";

      private static final String OAUTH_ATTRIBUTE_NAME = "xiAttributeName";


    Not sure how we can use them for OAuth authentication . If you have any documents or knowledge for the same please share .We were referencing Advantco Rest adapters but could not match their parameters in the SAP OAuth bean available.



  • Hi Alexander,

    I have to call a REST-Service from PI using a communication channel with the REST-Receiver adapter.

    The HTTP-Header Content-Type has to be set to "application/xml".

    But no matter what I try, it is always Content-Type:text/xml and or


    If I maintain the HTTP-Header content-type "application-xml" the message protocol shows the chainging of the HTTP-Header content-type to application/xml but the service responses "Bad Request".

    If I test the service with SOAPUI it works fine, setting the media-type to application/xml.

    Can you tell me how to maintain this header field?



  • Hi Alexander,

       We are using PI 7.4 with SP9, We have a scenario to connect a non-SAP server with REST to post the data but using OAUTH 2.0 token. However the tricky part is that the IDP is external to AS-ABAP and also to the server we are connecting.

    1. Can we do a look up with REST adapter and get the TOKEN from external IDP in the mapping.

    2. From step-1, use the TOKEN to pass through HTTP headers dynamically to call the REST service to post the data to non-SAP server.



    • Hi Sumanth,

      we do support OAuth 2.0 SAML bearer token with 7.4 SP10.

      Otherwise, you may implement the flow using BPM.

      Another alternative would be using SOAP with Axis and the STS Client Module

      For latter, see SAP notes 1039369 (FAQ XI Axis adapter, question 34 of receiver adapter), and 1980095 (Configuring PI to use Security-Token-Services (STS)).

      Big disclaimer on this: Though I have to admit, this is pure brainstroming, I haven't tried out any of the proposed alternatives on my own.


  • Hi Alex,

    I am trying to do a POST to a SAP system which requires that the CSRF token and session is provided in the HTTP Header of the request.

    I know that these can be retrieved in a GET operation, but I was wondering whether there was any way to include them in a single POST call using the REST receiver adapter?



      • Hi Alex,

        Thanks for the reply, I really appreciate it.

        My problem is that the values for the token and the cookie are dynamic and accessible first via a GET call.

        What if I need to do a POST, is it possible to configure the adapter to do both a GET (to retrieve the Header values) then do a POST with the values returned?



  • Hi Alex,

    I have one query on the PI Rest adaptor.

    Previously we have used Advantco Rest adapter and if any exceptions we used to get the fault response back and can see the fault message in the channel logs.

    But where as in PI Rest adapter I am not able to see the fault response.

    Can you please let me know if the PI Rest adapter can handle fault messages?

    I have also used the option Error Handling in the channel which will take the custom message content. But can you please let me know it can take the fault message from the mapping?



  • Is there a way to fetch header values that are coming back in a synchronous response message? Specifically we want to store the C-XSRF-Token which is populated in the header of a response message. We would like to access this header field in the response mapping. Can I somehow achieve this in a REST receiver channel setting or using a UDF / AM?

    My sender is a SOAP Channel.

    • Hi Peter,

      this is planned to be supported with the next SP shipment, i.e., 7.31 SP17 / 7.4 SP13, supposed to be delivered in November this year.

      The new enhancements will store all http header values in dynamic attributes, furthermore it will be possible to set the http header of the response


      • Hi Alexander,

        Need some confirmation, we are on PI7.4 Sp11. Does PI REST Sender adapter (Polling mode)    support adding custom headers, like ACCEPT...etc.

        we tried to use it in given HTTP Header option...seems its not working..!

        neither any SAP standard doc. confirms it for Sender rest channel.



  • Hi Alex!

    We have just updated our PI 7.31 Java-only (DEV) from SP 16 to 17 and the REST Adapter stopped working properly! All kinds of HTTP Request (POST, GET, PUT, etc) are processed as POST. For example ... we have tried to send GET Requests with Chrome (via Browser), Google Advanced REST Client, SOAP UI, etc., but when we check the message attribute "operation" at PI Message Monitor, all we see is POST! Any idea, please?

    • Hi Julio Cesar,

      I haven't encountered similar issues on the systems that I run my tests, I would propose that you open an incident ticket on the component BC-XI-CON-RST


      • Hi Alexander! I have just found out there is kind of a cache issue here! If I edit/save the communication channel and then send a GET Request, it works! But if I edit/save the communication channel and then send a POST followed by a GET, the communication channel understands these two requests as POSTs.

        ps: I have two operations at "Operation Determination" tab (POST and GET). POST is the first one!

        I will open the incident because I am not sure if this is a problem with my system or with the SP!

      • Hi Alex,

        I'm facing an issue of getting token from the HTTP response header using the REST adapter. If the adapter is updated with the capability how do we use it in UDF or what should be the header parameters to get the token and session id.


  • Hi Alexander,

    Thanks for the blog and it really helps people who are new to  REST.

    I have gone through it and I didn't understand what to give for "Value Pattern".

    Is it same for all scenarios? if not what is the standard I should follow?

    My requirement is :

    I need to pass value to header element: Authorization.

    I thought to pass my value to one of the Adapter Specific Message Attributes (to Operation attribute) and provide same in 'HTTP Headers' in channel config, but got stuck what to provide for "Value Pattern".

    Appreciate your help.


  • Hi Alexander,

    Not sure why, but I'm unable to see the blog on PI Rest adapter (though I can see the name in the heading).  I can see the below blog info instead of "PI REST Adapter – Define custom http header elements". Can you please check this once.

    The IdM 7.2 Config Analyzer – A deeper look inside

    In this blog I want to give a broader overview on the IdM Config Analyzer as the SAP document “Using the Configuration Analyzer” did. Also I want to visualize the config analyzer a bit more.
    At first I will go into the configuration options in detail. After that the output of the config analyzer will follow as well as interpreting it for some examples and telling you what has to be done in these cases. At the end I will sum up the benefits of the config analyzer and give an outlook on the migration sidesteps we experienced so far...........


  • Hi Alex,

    Fantastic information in this set of blogs on the REST adapter,  got me, I hope 90% of the way.  I was just wondering if there is a solution to Glenn's post regarding fetching the x-csrf-token and using it within the same POST operation adapter configuration.  I guess it would be similar to how OAUTH is behaving.

    I am able to perform each operation separately, but IDM does not recognize the token as current and gives me a 403-Forbidden error.    Thanks

  • Hi Alex,
    I am not sure if you saw my message from October 11, since it was during the scn switch over, but I received a response back from SAP and it does not appear that the REST adapters is a viable solution for x-csrf-token authentication at least with SAP IDM.

    SAP's suggestion by their development team was to try to handle it with two separated channels. Which is how we tried to implement the solution based on previous comments in this blog.

    I would think this is not limited to IDM's implementation of x-csrf-token.


  • Hi Alex,

    We are on PI 7.4 SP 13,i am not able to find any how to do or step by step approach to pass below three HTTP headers to JSON Request.

    1. Content-Type: application/jason

    2. API: Hard Coded Value

    3. IMS Token: From Incoming XML Payload i am getting this value,but i need to pass this to header.

    Could you pls tell me how to achieve this using receiver rest adapter.

    Thank You,


  • Hi Alexander
    We are on PI 7.4 SP 14 and scenario is to connect with AWS hosted API. For this autorization header needs to be updated with dynamic signature so for testing purpose i am providing constant value in HTTP header which is working absolutely fine in Postman but with REST adapter I recieve following error Peer sent alert: Alert Fatal: handshake failure

    It seems even though I am providing all the required parameters in HTTP header tab but still AWS is not recognizing them. I used XPI inspectpor but not able to see the payload which is actually going out to API.

    Can you pls. help.

  • Hi Lalit,

    No i do not find any solution so far,SAP suggested to apply some patches and we have applied but still same issue,pls let me know if you are able to find the solution for this.

    Pls share with me your contact number so that i could reach you to discuss on this.

    Thank You,


        Hello, We have the same issue, do you have any update ?

        We are using a CC REST to send a request to AX Dynamics and it's like the HTTP headers are not taken into account. If we test in Google chrome with the REST tester it's working.

        We are in SAP PO 7.50


        • Hi Johann,

          I didn't find a solution with rest adapter..because our PI version dont have the HTTP header tab.

          I found a alternative solution, change the  interface to IDOC-->PI-->IDOC (ack change the idoc status if the call to Rest service fail)

          i'm calling the post rest service with HTTP header parameters from message mapping with a java code,




  • Hi Alexander Bundschuh,


    I am following below blog to get the access_token value using rest lookup and I need to pass this token value to custom HTTP Header table of REST receiver channel -


    However, I dont have field called TOKEN at target structure, is there any way to directly assign TOKEN value from UDF to custom HTTP header table of REST adapter?





  • Dear Alex, thanks for sharing lot of valuable inputs.  I have a question for a one scenario we face difficulties to configure. We have a sync Rest request/response interface to an application which is misusing HTTP 200 to respond both application success and application error (e.g. business partner Id not found) . Since there are two different response messages for single HTTP 200 code I am wondering if there is a way we could trigger custom error handling based on the response as we do not know against which XML to map response (can be success as well as failure).  Please note that message roots are different so we can't use a single mapping. The only thing is that application errors always come with the same structure. Thanks for any inputs.

    Peter -

  • Hi Alex.

    I'm on the REST sender adapter tab "Result HTTP Header".

    I need to add a http header if it exists in the ASMA. If the header is missing in ASMA it shouldn't be added.

    How can this be done?

    Adding the header with default value isn't ok.

  • Hi Alexander,


    we got one business requirement where we need to call the JSON API in our ESS portal.

    we need to call the API using the authorization token generated run time dynamically.

    Process : – first we have to pass one token id and then get the One more access token.

    Based on the above second  access token call the below API.


    Update a member API end point in QA:{memberId}

    I am new to This topic.

    so kindly can u help me asap  with the complete solution step by step.



  • Hi Alex,

    This very nice blog!!!

    I am using receiver REST adapter with POST.

    We are using synchronous call.

    It seems by default Content-Type = "Application/xml"

    How I can convert to "text/xml".

    Which all are Content-Type SAP PI supports.

    It is urgent , Kindly revert.



    Jignesh shah


    • Hi Jignesh,

      by default, if you select XML as format application/xml is set, if you use JMS it would be application/jms

      To be honest, I'm not sure if you can overrule this. Have you tried to configure header field content-type text/xml in the http header configuration? If this doesn't work, I doubt that you can change it via configuration, in this case an own adapter module may help