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 */
&mRequest.OverrideURIResource("http://httpbin.org/post");

/* 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 (taken from PeopleBooks):

Local XmlDoc &Output;
Local String &Exception;

Local Message &MSG1, &MSG2;

&MSG = CreateMessage(OPERATION.QE_FLIGHTPLAN);

&MSG.IBInfo.IBConnectorInfo.ConnectorName = "HTTPTARGET";
&MSG.IBInfo.IBConnectorInfo.ConnectorClassName = "HttpTargetConnector";

&nReturn = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties
    ("Method", "GET", %HttpProperty);
&nReturn = &MSG.IBinfo.IBConnectorInfo.AddConnectorProperties
    ("URL", "http://finance.yahoo.com/d/quotes.txt/?symbols
    =PSFT&format=l1c1d1t1", %HttpProperty);

&MSG2 = %IntBroker.ConnectorRequest(&MSG, true); // user exception property (true) passed

If &MSG2.ResponseStatus = %IB_Status_Success Then
    &Output = &MSG2.GetXmlDoc(); // get the data out of the message

Else
    &Exception = &MSG2.IBException.ToString()); // read the exception

End-If;

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.

Comments

will

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

Both of the methods should be available in 8.55.17. Which method are you using when receiving a response of 0, the ProvideRestTest method or the ConnectorRequest method?

Colton Fischer

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?

Raju Dola

Hi I am trying to invoke my RESP API using ConnectorRequest. Its working as expected for Httpstatus codes 200. But for 400 and 500, I am getting the below issue and response is blank..

Integration Gateway - HttpTargetConnector:ExternalApplicationException. Http status code HttpStatusCode returned : 400. (158,10623)

Colton Fischer

Hi Raju. HTTP 4XX errors usually indicate that the request is invalid is some way, while HTTP 5XX indicates that something went wrong on the external server. You should expect the responses for 4XX and 5XX status to be blank.

The 4XX and 5XX type responses are fatal. You could always wrap the request in a Try-Catch to catch the ExternalApplicationException, however there is not much “recovery” that can be done for these types of errors.

I would suggest reviewing the REST API to ensure the requests are valid. Valid requests should always result in non-4XX response. The external server logs should be reviewed to determine the reason for the 5XX responses.

I hope this helps.

Raju Dola

Hi Fischer,

Thank you for the quick reply. I understand about the 4XX and 5XX.. But my client is providing specific error messages when I get 4XX and 5XX. I need those error response messages.. Is there any way to get theses 4XX and 5XX messages?

For Examples - { “statusCode”: 400, “errorMessage”: “Invalid TS_CATEGORY” }

Colton Fischer

I don’t have an API that returns 4XX/5XX statuses with response message content to test this on. If you are finding that the response contains empty content for 4XX/5XX statuses, then it is possible that IB is “eating” content for these scenarios. This could be a bug or by design.

You can try asking this question in the PeopleTools MOS Community to see if any of the experts have opinions or solutions for this issue.

Aditi

Hi Colton, I am using CallRESTAPI method and passing parameters Third Party URL, PUT method, xml request message and Key (Not required for sandbox so it’s blank in my case). Also adding segment header keys the way I am doing it in Postman. In postman I am getting successful response but in PeopleSoft I am trying to achieve same using CallRESTAPI, I am getting error- 415- Unsupported Media Type.

I checked Content-Type Header key being used in CallRESTAPI, it’s same as we are using it in postman. Can you please help me with this

Colton

I am not sure what the CallRESTAPI method is. Can you share the PeopleCode that you are using to make the request? That would help me in understanding what the issue might be.

Leave a comment

Your email address will not be published. Required fields are marked *

Loading...