PeopleSoft REST Services

PeopleTools has not always supported a REST style interaction with web services. Historically, web services were all “HTTP POST” operations. That is what we have documented in HttpListeningConnector. With REST, all transactions are submitted to the RESTListeningConnector.

• PeopleTools 8.51 and lower has no support for REST services
• PeopleTools 8.52 (released October 2011) has some REST support.
• In PeopleTools 8.53 there is some support for JSON but it is buggy, very buggy. 🪲 🐛 🐜
• Starting in PeopleTools 8.55.11, there is better support for JSON using a new built in JSON Parser. I wrote about that here:
  • JSON Parsing using PeopleCode Classes Starting in PeopleTools 8.55.11
  • JSON Parsing Using PeopleTools JsonParser

The REST style is pretty much the de facto API paradigm on the web as of this writing. You do NOT see new cloud or SAAS applications rolling out SOAP or RPC web services. REST has pretty much won. It is not perfect. However, since the REST style piggy backs on the HTTP protocol it has broad support on almost all programming languages. It is super easy to test with testing tools for every platform.

There is GraphQL that is getting a ton of investment. However, GraphQL will likely never be supported in PeopleSoft and it is just for doing queries as best as I can tell.

There are many other types of RPC based protocols across the web. Protocol Buffers is an impressive one developed by Google. I code most of my side projects in Go and there is some great libraries for Protocol Buffers. We will never see any support for that in PeopleSoft so we can only look from afar in admiration when wearing your PeopleSoft Developer hat.

What is different about REST?

• REST has very descriptive URLs. In the REST model, the URL specifies a unique resource on the web. For example a RESTful url may look something like this:
  • http://cedarhillsgroup.com/users/cmalek/roles.xml
  • In the above URL the request is asking for and xml file containing all the roles assigned to the cmalek user id from the user module. (read from right to left).
  • In the old SOAP or RPC model only one URL is every used and the payload or HTTP headers told the server what code/handlers to run.
• REST Relies on HTTP return codes. In the REST methodology, HTTP status codes have special meaning and they should be used. It turns out PeopleTools does not fully support this paradigm and there are many rough edges around using different return codes.
  • In the old SOAP or RPC model, HTTP status codes were not used and every implementation may have signaled result codes differently putting a heavy burden on each integration.
• REST Relies on HTTP verbs. REST makes use of GET/PUT/DELETE/POST methods to infer if the data should be updated, retrieved, deleted, etc.
  • In the old SOAP or RPC model, generally everything relied on POST.

If you want to learn more about REST, I would spend some time on google. I would probably start at Best Practices for Designing a Pragmatic RESTful API

Lots of Rough Edges

The more recent PeopleTools versions do have support for REST. However, the functionality can have many rough edges. If you have spent a lot of time working with service operations over the years you will find REST can be frustrating. My feeling is that the Oracle team forced the REST style onto a technical structure of the original old style service operations. It just feels clunky. It is a bit like a square peg in a round hole. I don’t blame them one bit trying to leverage the existing framework. It is not one thing that I can point to that makes it frustrating but a culmination of many small little UI and technical issues. It has been getting better and better with every tools release but I have not seen major improvements in the technology. The support and documentation for JSON is abhorrent in 2019.

Targeting PeopleSoft REST Endpoint

For a client to target a REST end-point in they must target the RESTListeningConnector. You will see that REST service operations have many of their parameters in the URL path like the target node and the operation name. Parameters can also be in the URL path. In PeopleSoft only the Synchronous style is supported. You cannot do Asynchronous processing out of the box. If you do need to do some sort of long process in a REST service operation generally the approach you take is to schedule a batch process or enter data into a table that will be picked up by some batch process later.

Should I use REST in PeopleSoft

Yes you probably should going forward if you are on more recent PeopleTools releases despite all the rough edges.

A Note for Developers New to PeopleSoft

If you have not been around PeopleSoft for more than a few years you are at a slight disadvantage on some fronts. PeopleSoft has a long history going back to the early 90s. It has changed in many areas over the years. With any technology, there are many dark corners and abandoned modules. Some of these dark corners still have an imprint on the current system. As someone new to PeopleSoft, it is hard to know what to avoid and where the landmines are. If you find yourself asking “why is it structured this way?” it is likely due to some legacy functionality. With my 20 years of PeopleSoft development experience, I see a lot of these dark corners when looking at the REST functionality. There are pieces that that don’t really do anything but are required (routings and services). However, they are needed because of the legacy code structure. Oracle made a decision to try to make the REST functionality work within the technical structure that was there. From my perspective, I can see the reason for that and the need for those unneeded pieces that seem to be doing nothing. Don’t get discouraged when working with the framework..