PeopleSoft RESTListeningConnector Not So "RESTful"

I have been meaning to play around with the new REST based Web Services in PeopleTools 8.52 and 8.53. I was excited to see that as of 8.53, PeopleTools is finally getting support for JSON. (It is about 8 years late but what you gonna do?) This is a “first impressions” post.

I fired up a new HCM 9.2 on Tools 8.53.02 VirtualBox image downloaded from Oracle support. I was very surprised that it “just worked” for the most part. I dug around to see if there were any delivered REST Web Services that I could play around with to see how the functionality work.

I found the Service Operation PTLOOKUPXLAT_REST_GET. This looks like a service operation where an external system can “ask” for the valid values for a field that has XLATS and other variations of that request. Basically, it appears to be everything about XLAT values.

The response will be different based on the “URI”. How did I know this? Look at the URI grid in the screen-shot above. It is intuitive based on the URL of the request. This is the thing I love about REST. The URL structure is the interface and it is explorable in a web browser or a Command Line application like curl.

First, I made sure the routing and handlers were in place which I will not cover here. I decided to try to perform a “GET” request to see what happens and how the RESTListeningConnector behaves.

I used the following URL:

http://192.168.0.3:8000/PSIGW/RESTListeningConnector/PTLOOKUPXLAT_REST.v1/XLAT_Lookup/USERIDTYPE?fieldVal=CID

I am going to guess that the URL should return some information about the translate values for the field USERIDTYPE with a value of “CID” (look at the end of the URL closely). I would expect some information returned from the web service like the long and short translate table descriptions and maybe some other items. (I am not really sure, we are just exploring.) However, that is not what happened. In fact, the response I got back was not very “RESTful” at all.

I was using a OSX application called “HTTP Client” that is no longer. which makes this sort of stuff really easy. You can also use curl or PostMan. Let’s see what happened.

The Client Request

First let’s example the very simple client request.

The screenshot shows the HTTP Client interface which shows that we did a “get” request and added one HTTP header of Accept: application/json. That header should tell the RESTListeningConnector to return a JSON document. This request is very simple. There was no HTTP body or other headers.

The Server Response

What I got back from the RESTListeningConnector was completely unexpected. Let’s take a look.

• We got an HTTP Status Code of 200 which means “success” or “all is good”
  • This would tell a client application that the expected JSON information is in the HTTP response body but as we see that is not what is there.
• We got XML back when I asked (via the header) for JSON
• The data returned in the XML was actually an error but that is buried in the XML.

It appears that my integration gateway is not configured correctly which must be an issue with the VirtualBox image as I did not touch anything. I will have to dig into that which is not the point of this post. This gateway misconfiguration could happen in a production environment yet the RESTListeningConnector does not behave RESTfully. Even if my gateway was configured improperly I would expect the RESTListeningConnector to do the following:

• Return an HTTP Status Code in the 500s
  • This would tell the client that there was a server error and “It is not their fault, try again later”.
  • An HTTP status code of 200 (ok) was completely inappropriate in this situation.
• Return a response based on my requested data format which was JSON in this example even if that response contains that same server error.

There is some mention in the 8.53 release notes that if the “Service Configuration” is in Production mode this should not happen. However, I double checked that I am in production mode and rebooted the images. The same non-RESTful behavior still occurred.

Imagine if this was a browser based application in JavaScript. The code would have saw the 200 status code and tried to parse the response as JSON but it actually contained XML and a cryptic error code. It would have broken the application without much useful information to the user.

I think Oracle has some improvements to be made here.