REST Web Services - PART 1

PeopleTools REST Web Services Part 1

I recently presented at Oracle OpenWorld on the subject of REST web services in PeopleSoft.  REST based web services were introduced in PeopleTools 8.52 and I'm hoping this series of blog posts will help newcomers to both Web Services and REST.

What is REST?

REpresentational State Transfer (REST) is a style of doing Web services that is becoming increasingly popular among web developers due to it's simplicity over SOAP and other methods.

REST follows 4 basic principles
1) All content has a unique id by which it is referenced (URI)
2) services are invoked using standard WWW operations of GET, POST, PUT, DELETE
3) all REST services are stateless in that they retrieve a representation (copy) of the content requested
4) REST is synchronous only. Designed for point to point communication

You can invoke a REST web service simply by using it's URI.  For example an example REST web service to GET PeopleSoft operator details might look like this.

http://myserver/PSIGW/RESTListeningConnector/Operator.v1/oprid=VP2


Documents

Understanding the PeopleTools Document object is necessary to building REST based web services in PeopleSoft so let's cover some of the basics.

What is a Document?

Documents represent a hierarchical data structure a lot like a Rowset object.  They have a logical representation and a physical representation in the form of XML, HTML and JSON (from Tools 8.53).

Documents can be grouped together in a Package and like other Integration Broker object definitions can be versioned.

Document Data Types

A document is a tree structure representing data.  As such, every document has ROOT element that is the name of the Document.

There a four basic data types
*Primitive.  An element that has one of the simple data types of integer, string, character, date, time, etc.
*Compound.  An element that contains 1 or more primitives (think Record definition)
*Complex Primitive Compound.  A primitive element that has attributes. (think XML attributes ElementValue )
*Collection.  An element that is a repeating group of Compound and/or Primitives. (think Rowsets)



What Role do Documents play in REST Web Services?

A Document is required to collect the inbound URI parameters from a REST web service call.  This is done by mapping the URI parameters to document element names.  This is called the Document Template.


The next post will show how to create Service, Service Operations and Handlers.
All the code used in this series on REST can be downloaded from here http://goo.gl/KUX9F2

Comments

Dave Horne said…
Graham, Great session. I downloaded your project; however, it appears that the getOperator application class is empty. I also get an error when trying to execute the operator_post operation as follows:
EXCEPTION!!
Service Version %1 for Service %2 not found in DB.

Yet everything seemed to load perfectly from your project.
Graham said…
Hi Dave, can't believe I didn't pickup on this sooner. Sorry you had problems. I've corrected the project and if you download again it should be ok now.

regards
Graham
Dave Horne said…
Graham, Thank you, I've downloaded the new project and the getOperator application class works terrific. However, I still get the EXCEPTION error message mentioned previously for the operator_post operation. I can't seem to figure out why that one is still not working.
Dave Horne said…
The error seems to be somewhat related to the operation being defined as a POST event. I converted the operation to a GET event and it works just fine. I tried to create another POST event to access the same application class and I get the same error message.
Dave Horne said…
Graham, I have another question that has stumped me on the security side of REST services to PeopleSoft. As I have successfully got this web service to work, I now want to pass in a usertoken so I can control who can access this web service via a permission list. I can't use basic authentication because we do not use Oracle Security for authentication we use external security and pass in the user token as follows in a SOAP packet:


userid


How do you do this same authentication for REST webservices?
Dave Horne said…
The SOAP entry in the header is like this:

<wsse:UsernameToken>

   <wsse:Username>userid</wsse:Username>

</wsse:UsernameToken>
Unknown said…
This comment has been removed by the author.
Unknown said…
Graham: hope all is well. I downloaded your project and it works great!. Thanks for sharing.

I have a quick question.

Cna you please guide me how to GET multiple rows in the XML output?
Unknown said…
Hi Graham, I downloaded your project.
I am facing problem while testing the rest web service.
I am getting following error:

Unable to find a routing corresponding to the incoming request message

I am getting above error only in case of rest web services. CI based web services are working fine.
Siddharth said…
Hi Graham,

I am awaiting a Part 2 of this blog eagerly.

I have a doubt that is it necessary to have "Document" type of Message to achieve a REST Webservice?

Could we use a "Non-rowset" or "Rowset" based Messages instead?

Also, could you elobrate more on the fact that how we could implement Security into REST based services? How do I include the security information in a Document.
Chandra said…
Graham, we have tools 8.53.11,
I am trying to consume REST webservice into peoeplesoft, However, consume webservice functionality only works with WSDL file not the WADL. How do i accomplish consuming rest service.

Once, I consume, could you please point to code samples on how to send a reqeust.


SOme of the post are saying about your downloadable project. please let me know from where can i download.

Chandra
Chandra said…
Graham, we have tools 8.53.11,
I am trying to consume REST webservice into peoeplesoft, However, consume webservice functionality only works with WSDL file not the WADL. How do i accomplish consuming rest service.

Once, I consume, could you please point to code samples on how to send a reqeust.


SOme of the post are saying about your downloadable project. please let me know from where can i download.

Chandra
Hello Graham,

I've configured REST services and able to get the results in Service Operation Tester but getting "UserName not defined in database. (158,55)" exception when i test it in browser and using sendmaster utility. Did you come across this situation? Am i missing something in the configuration?

URI: http://myhostname:port/PSIGW/RESTListeningConnector/operator.v1/?oprid=PS
Syed Usman said…
Hi Dave & Fraham,

Were you able to find solution for external authentication in REST web service? As we want to go through Sign on peoplecode once user provide user name & pwd for Get operation in REST service.
Alex moner said…
PeopleTools 8.52 and I'm hoping this series of blog posts will help newcomers to both Web Services and REST.
Thailand market entry entry services
Allan said…
This comment has been removed by a blog administrator.
Unknown said…
Hi Graham,

Hope you're doing well !!!

I found your blog very informative and also downloaded your project. The problem I'm facing is when I try to import the project in Application Designer I get the following message:

"The requested project contains an unsupported definition type, and can not be opened. Project must be opened using a release of Tools that supports the definition type."

We're on tools 8.52.07

Is this project not compatible with 8.52? I appreciate any information and help.

Thanks,
Pradeep
sharma.pradeep2014@gmail.com
mantra said…
Hi Graham,
Its really a useful post to understand the REST services. I tried a similar one and it works great . But I need to know how to retrieve a multiple rows in the XML output ? Please help me out.
Aditya Saxena said…
This comment has been removed by the author.
Anonymous said…
This comment has been removed by the author.
I know this is a rather old thread but I am hoping to learn more about utilizing this technology within PeopleSoft. We are using HCM and are on PeopleTools 8.54.14. I have imported the project and have verified all settings suggested in this blog and have reviewed all of the attachments. I continue to receive the following error, "Unable to find a Routing corresponding to the incoming request message." I'm not sure if it is a corrupt routing or if I just have missed something else that should be obvious. Any help you can provide would be HUGE. Thank you in advance...

Tom
Anonymous said…
Great Work. This post is worth everyone’s attention.
Hire ICO Expert In Singapore
Annie said…
Hello,

Do you have any Peoplecode sample where the URI will be fetching multiple values for a single request field? I was thinking the document will have a collection, and under it a primitive field, is it correct?
Viktor said…
Thanks for the post. I am having an issue. Please, help.

I have this tree

COL
COM
COL
COM (Personal)
COL
COM (Address)
COL22
PRIM (First_Address)

I can't get the COL22 to read PRIM (First_Address) COL22 can't convert to PRIM(error)


&COL_1 = &COM_Root.GetPropertyByName("Collection11");
&COM_p = &COL_1.CreateItem(); /* PErson1 Compound */

&COL_1_1 = &COM_p.GetPropertyByName("Collection33");

&COM_Personal = &COL_1_1.CreateItem(); /* Personal2 Compound */

&COL_6 = &COM_Personal.GetPropertyByName("Collection66");

&COM_Address = &COL_6.CreateItem(); /* Address Compound */

&COL_6_2 = &COM_Address.GetPropertyByName("Collection22");

After here I'm not sure.....

Thank you for your help


Wing Cheung said…
How can we return empty collection like following?

{
"status": "Success",
"scheduleList": []
}

"status" is Primitive
"scheduleList" is collection

I put the following to show the "scheduleList" tag

&collScheduleLists = &compResp.GetPropertyByName("scheduleLists");
&compScheduleList = &collScheduleLists.CreateItem();
&nRet = &collScheduleLists.AppendItem(&compScheduleList);

but it will show all the Primitive with empty string in the collection
{
"status": "Success",
"scheduleList":
[
{
"Date": "",
"Time": ""
}
]
}

If I remove the code, it only show the status

{
"status": "Success",
}

Could you help?

Thanks
Wing