Easy REST Requests

One of the biggest pain points with using Integration Broker to consume third-party REST web services is the creation of all of the required metadata definitions.  If I want to perform a simple REST request to a third-party URL, then I am stuck having to create Message, Service, Service Operation, and Routing definitions.  Sometimes I just want the ability to test an API without having to create all of these definitions.  It turns out that there are a couple of delivered methods within the %IntBroker class that allow developers to code the consumption of a REST API without the need to create all of the metadata definitions listed above.  The two methods that I will be discussing are the ProvideRestTest and ConnectorRequest methods.

The ProvideRestTest Method

Delivered usage of the ProvideRestTest method can be found behind the Integration Broker Service Operation Tester Utility.  This utility is located under Main Menu > PeopleTools > Integration Broker > Service Utilities > Service Operation Tester.  It appears that this method was created to ease the process for this utility to make generic REST requests.

Although undocumented, the ProvideRestTest method is included in the %IntBroker class and can be used within a PeopleCode program.  Below is a sample of code that makes use of this method to send a simple POST request to a third-party URL:

/* Get the request message from a generic REST-based Consumer Service Operation */
Local Message &mRequest = CreateMessage(Operation.IB_GENERIC_REST_POST);

/* Set the third-party URL to send the request to */

/* Populate the request message with data */
Local boolean &bRet = &mRequest.SetContentString("My Data");
&bRet = &mRequest.AddSegmentHeader("MY-CUSTOM-HEADER", "XXX");

/* Perform HTTP POST */
Local Message &mResponse = %IntBroker.ProvideRestTest(&mRequest, "POST");

/* Output the reponse code and response content */
MessageBox(0, "", 0, 0, String(&mResponse.HTTPResponseCode));
MessageBox(0, "", 0, 0, &mResponse.GetContentString());


The ConnectorRequest Method

The ConnectorRequest method of the %IntBroker class is the more well-known (and documented) method that allows to make easy REST requests to third-party URLs without having to do a ton of setup.  Documentation and sample usage of this method can be found in the Bypassing Integration Engines to Send Messages section of PeopleBooks as well as in the snippet below:


The biggest caveat that I have found to using the ConnectorRequest Method for REST requests is that the resulting response message does not contain the populated HTTPResponseCode property.  This forces the developer to decipher the status of the response by parsing the body of the response message. The fact that the HTTP status code is absent from responses, makes the ConnectorRequest method not very friendly for working with REST responses.  Other than this shortcoming, I believe the ConnectorRequest method is great for making easy requests.

Important details

One important piece of information to note is requests that get sent with the ProvideRestTest and ConnectorRequest methods will not appear in the Synchronous Services Operation Monitor.  I believe this is due to these methods bypassing the Integration Engine when sending the request messages.  This appears to be true regardless of the specified value for the Log Detail field of the corresponding Service Operation Routing.

Another important detail that often goes overlooked when consuming secure (https) third-party REST APIs is that the third-party SSL certificates must be added to the PeopleSoft keystore in order to send request messages to the third-party URL.

Closing Thoughts

Both of these methods are suitable for making easy REST requests in PeopleCode.  As we saw in this post however, the ProvideRestTest method is undocumented (unsupported) and the ConnectorRequest method has a vital shortcoming that makes it less appealing to be used for making REST requests.  Hopefully we will see delivered support for the ProvideRestTest method and/or additions to the ConnectorRequest method in future PeopleTools releases.

13 thoughts on “Easy REST Requests

  1. peter says:

    how to invoke https rest service? from china.i have imported certificate. howev er, it still tells me untrusted cert chain

  2. will says:

    This looks interesting … is it in Tools 8.55.17 I am trying to do a POST
    All the setup for a regular rests is wild… A simple URL and Parameters And get results is great

    I tried this but I get a response of 0. Is there something missing

    • Colton Fischer says:

      Hmm, that is odd. I am not sure why this is not working for you. Which URL and HTTP method are you invoking? Are you invoking the same URL and HTTP method in the example in this post?

      UPDATE (5/18/18): I just came across this issue as well where the HTTPResponseCode property returns 0. In my scenario, I was trying to access a secure (https) URL. To troubleshoot the issue, I created a node to represent the external URL. When I attempted to ping it, I was getting a the Integration Gateway External System Contact Error (158,10721). When I looked at the IB logs, it said HttpTargetConnector:ExternalSystemContactException java.security.cert.CertificateException: Untrusted Server Certificate Chain. I added the SSL certificate for the URL I was trying to reach to the the PS web server keystore and bounced the web server. Now I am able to ping the node successfully and the HTTPResponseCode property is properly populated when I invoke the secure URL with the ProvideRestTest method. Hope this helps.

  3. kayazah says:

    Good day Colton! I tried to implement the ProvideRestTest Method yet I am getting 0 HTTPResponseCode. I am still learning on how to use the REST web service and hope you can give some tip.
    Local Message &mRequest = CreateMessage(Operation.IB_GENERIC_REST_POST);

    /* Set the third-party URL to send the request to */

    Local boolean &bRet = &mRequest.SetContentString(“id”);
    &bRet = &mRequest.AddSegmentHeader(“userId”, “4”);

    /* Perform HTTP POST */
    Local Message &mResponse = %IntBroker.ProvideRestTest(&mRequest, “POST”);

    MessageBox(0, “”, 0, 0, “Test 01:” | String(&mResponse.HTTPResponseCode));
    MessageBox(0, “”, 0, 0, “Test 02:” | &mResponse.GetContentString());

    • Colton Fischer says:

      Hello Kayazah. I see that you are posting to a secure (https) url endpoint. If you want to interface with an https url, then you must import the third-party SSL certificates to the keystore on the web server. If you are looking to test the service without doing this, then you can try invoking the same url endpoint without “s” and use http instead. Hope this helps.

  4. Mark says:

    Hi Colton –

    Good day! I am still having zero returns. How about the URL needs an authentication, how am I going to include the LOGIN & the PASSWORD?

    • Colton Fischer says:

      You can include authentication credentials in the request by adding an additional header using the AddSegmentHeader method. I am unsure of the type (if any) of authentication that the third party requires so it is hard to provide a concrete example.

      However, I suspect the zero response is occurring due to an issue on the PeopleSoft side and not the third party. I would suggest looking at Integration Broker logs that occur when you make this request. This might lead you in the right direction.

Leave a Reply

Your email address will not be published.