Understanding SOAP versus REST versus HTTP web services in PeopleSoft

This section pertains to synchronous web services which we will go into great detail in the later sections of this book.

Synchronous Service Operations are characterized as a request/response interaction style. The client sends in some request to PeopleSoft and it waits while PeopleSoft gets or updates data and generates a response and sends it back.

There are 3 different ways you can invoke these types of service operations.

• REST
• HTTP Post
• SOAP

REST

REST uses the HTTP protocol extensively. It attempts make use of many of the HTTP protocal features including HTTP verbs (PUT, POST, DELETE, GET) and HTTP Status codes. REST was introduced in the Integration Broker with PeopleTools 8.52.

With REST:

• Clients submit requests to the RESTListeningConnector
• The name of the service operation being called is included as part of the URL path.
• Parameters could be mixed into the URL query string, URL path and HTTP Body depending on the API design.
• No Integration Broker nodes are used
• The security mechanism is generally using “basic auth” tied to a PSOPRDEFN.OPRID and password.
• Unit testing in Postman is very easy.
• The JSON support prior to 8.56 was extremely limited. Therefore, XML data format is the most supported encoding scheme.

Read more in the REST Introduction section

HTTP Post

Until REST was introduced in PeopleTools 8.52, the HTTP Post method via HttpListeningConnector was the best and most simple way to call service operations for external clients. This is more of an RPC style web service.

With HTTP Post:

• Clients submit requests to the HttpListeningConnector
• Normally XML data is submitted in the request and XML is returned. There is some support for other content types but XML is generally the default.
• The security mechanism is generally handled through HTTP headers and node settings.
• They are fairly easy to test and work with in an HTTP testing tool.

SOAP

SOAP is old, SOAP is bloated, SOAP does not make you clean (but soap does). Unless you absolutely have to use SOAP for some reason, I recommend using one of the other styles of messaging. This book will spend very little time discussing SOAP.

With SOAP:

• clients submit requests to the PeopleSoftServiceListeningConnector
• Messages must have a SOAP wrapper
  • This make testing not as simple as the other methods.
• Error responses are wrapped in a SOAP fault message
• Security is handled differently that the other methods and is arguably more complex.

Random Reasons NOT to use SOAP:

• It relies on the client to import SOAP libraries to that lead to more code dependencies.
• There can be subtle differences between PeopleSoft’s SOAP implementation and your client’s libraries leading to bugs and inconsistencies.
• Unit testing SOAP services with a tester tool like Postman is hard because the message structure is complex.
• WSDLs and XSD are a pain to work with and PeopleTools has basic support and lots of rough edges.
  • Additionally, I don’t really think WSDL’s and XSD provide that much functionality. They may give a 10,000 foot picture of the messages involved and maybe the URLs. However, they don’t get involved in the gritty detail at the field level and how different fields interact with one another. For example, if you give value “x” for field “A”, then the options for field “B” become limited further. That is not covered in those schema and where I find that 99% of the client code has to deal with.
• The documentation from Oracle is completely lacking. There are no start to finish examples, there are conflicting documentation articles, etc.

Just tell me which one to use!

• SOAP is out.
• The choice is between HTTP and REST.

If you are developing a bespoke solution for your specific organization and you are on the latest tools release then REST might be the way to go.

If you are a software vendor developing a PeopleSoft web service that needs to be deployed to unknown clients then HTTP might be a safer bet. I do a lot of work here. I have different clients that have software products that need to integrate with PeopleSoft. I have developed standard PeopleSoft web services that are deployed to various client sites that integrate with these products. In this situation you cannot target the most up to date PeopleSoft release. What often happens in this situation is that a client might be on an older PeopleSoft release and you need to have the code developed in a manner that will work for all possible clients. In this situation, I use HTTP and XML because it will be portable across a very wide range of clients. The software application talking to these web services will just know how to talk to those web services. The number of People in this situation is likely small.

To be honest I don’t see a huge difference between REST and HTTP due to the way PeopleSoft is structured. I will cover this more in later sections.

Opinion’s From Around the Web

• Simplicity and Utility, or, Why SOAP Lost
• REST Vs SOAP, The Difference Between Soap And Rest
• RESTful API Tutorial