550 likes | 780 Views
CON7553. PeopleTools REST Web Services: Everything You Need to Know Graham Smith - OXFAM GB PeopleSoft Technical Lead & System Architect. Oxfam. Oxfam is a vibrant global movement of dedicated people fighting poverty. 70 years experience in 94 countries
E N D
CON7553 PeopleTools REST Web Services: Everything You Need to Know Graham Smith - OXFAM GB PeopleSoft Technical Lead & System Architect
Oxfam Oxfam is a vibrant global movement of dedicated people fighting poverty 70 years experience in 94 countries Syria - Helping over 200,000 refugees
PeopleSoft @ OXFAM • HCM & FSCM Applications • 4,500+ users in 70+ countries • Working on 9.2 upgrade to FSCM
Agenda 1) What is a web service 2) What is SOAP & REST 3) What is WSDL and WADL 4) What is XML and JSON 6) Configuring PeopleTools for REST 7) What's delivered in a SYS database that works 8) How to Build a REST service 9) Testing tools 10) Security 11) Demo 12) Questions
What is a Web Service? • Method of communicating between devices over the world wide web • Characteristics of a web service • Defined interface in machine readable form (WSDL or WADL) • Conveyed over HTTP/S • Systems interact using request / response messages (SOAP or REST)
Introduction to REST • Style of doing Web Services • Defined by Professor Roy Fielding • @ UC Irvine in 2000 • Co-founder of Apache HTTP Server • Principal author of HTTP specification • Emerging as the predominant web API model • Lighter weight and easier to use compared to SOAP and others • Available from PeopleTools 8.52
What is SOAP & REST? • Both are used to access Web Services • One is a protocol (SOAP) with defined specification http://www.w3.org/TR/soap/ • One is an architectural style (REST)
What is SOAP? • SOAP Simple Object Access Protocol “SOAP Version 1.2 is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment” • TECHNOLOGY SPECIFICATION (W3C in 2033) • Requires custom methods (e.g. getCustomerName) • Uses HTTP POST method to send XML messages • Designed for distributed transactions • Extensible model (WS-Security, WS-Routing, etc) • Asynchronous and Synchronous communication possible • Built in error handling
What is REST? • REST REpresentational State Transfer • ARCHITECTURAL STYLE (not a standard) • Implements standard HTTP operations (GET, POST, PUT, DELETE) • Used to locate and return the representation of a resource (URI) • No XML to parse and process (fast) • Synchronous communication only • Stateless • Easier to implement
What is WSDL & WADL? • WSDL Web Services Description Language • XML to describe SOAP web service • Can define both SOAP and REST web services (from WSDL 2.0) • PeopleTools describes SOAP based service • W3C Recommendation 2007 • WADL Web Application Description Language • XML to describe REST web services • PeopleTools describes REST services using WADL • W3C Submission in 2009 by Sun Microsystems • Limited tooling support
What is XML & JSON? • XML eXtensible Markup Language • JSON JavaScript Object Notation JSON now supported PeopleTools 8.53
Configuring PeopleTools for REST • Set REST Target Locations in Service Configuration • Specify optional node name Target URL
Configuring PeopleTools for REST • Activate ~~Any~~ to Local Routing on GETWADLService Op
Configuring PeopleTools for REST • Set default application server in Gateway Setup Properties • Check and set PeopleTools version (inc. Patch number)
Delivered Example in SYS database • Service Operation PTLOOKUPXLAT_REST_GET • Returns XLAT values for a given Fieldname. • Handler App Package PT_IB_LOOKUPREST From 8.53 this is implemented as REST based service. An error may occur in the Handler code if Earlier than 8.53.06
PT_LOOKUPXLAT_REST_GET http://server/PSIGW/RESTListeningConnector/PTLOOKUPXLAT_REST.v1/XLAT_Lookup/RUNSTATUS?fieldVal=7
REST URI - Uniform Resource Identifier • Identifies the name of a web resource http://myserver/orders/data.html erfeufhefherf her hferfherhferfherheihfweewewewewewdwedwedewdweewdewdweewwe dew wewedewweewweewdweewwdewdweew dew weewewweewdwedewdewdewdewewdewdewdewdewdwe
REST URI - Uniform Resource Identifier • REST operates in a similar way to the WWW http://myserver/operators http://myserver/opeators/oprid=VP1 opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx opridxxxxxxxxxxxx VP1 xxxxxxxxxxxxxx
REST URI – Resource Templates http://myserver/operators http://myserver/operator/oprid=VP1 Resource name Resource name RESOURCE TEMPLATES
REST URI – Resource Document http://myserver/operators/oprid=VP1 /operators/oprid={oprid} Template Mapping by element name
How to Build a REST Web Service • Create Document • Test Document • Create Message • Create Service • Create Handler • Create Service Operation • Resource Template • Test Handler • Create Routings • Test Service Operation • Publish Web Service (if WADL is needed) Using delivered image FSCM 9.2.002.
REST Web Service Components REST Service • Service Operation • Resource Definition • URI Template(s) • Document Template • Response Message (200) • Fault Message (400) Resource Document • Service Operation • Resource Definition • URI Template(s) • Document Template • Response Message (20 • Fault Message (400) Message Response Document Handler (OnRequest) Handler (OnRequest)
Example REST Service Return the name and email address of a given operator. Service = OOW_OPERATOR Service Operation = OOW_OPERATOR_GET http://myserver/operator/vp1 Application Designer project OOW_REST Download from http://goo.gl/KUX9F2
1) Documents Definition • Define hierarchical data structures (logical) • Map onto physical structures • XML • JSON • Database records and fields • Data types available • PRIMITIVE = string, char, integer, etc • COMPLEX PRIMITIVE = primitive with attributes • COMPOUND = set of one or more primitives • COLLECTION = set of one or more compounds
1) Document Data Types • ROOT element • Collection • Record Compound • Primitive • Complex Primitive Compound
1) Documents Needed • Document Template • Used to retrieve inbound URI parameters • Cannot contain COMPOUND types • Supports direct variable substitution • Request Document/Message • Only required if using POST method • Response Document • Used to construct return message to client • Fault Document (optional) • Used to construct return message on error condition They can be all the same document or different ones
1) Create Document – Relational Allows mapping of document elements to PeopleSoft records and fields.
3) Create Message The DOCUMENT is not enough. A message of type Document must be created.
5) Create Handler • Create an Application Class that implements PS_PT:Integration:IRequestHandler • Create document from inbound URI Local Document &oprDoc = &_MSG.GetURIDocument(); • Get inbound URI element values from document&oprid = &oprDoc.GetElement("oprid").value; • If POST then get content body &str = &_MSG.GetContentString();
5) Create Handler • Create return message &returnMsg = CreateMessage(Operation.OPERATOR_GET, %IntBroker_Response); • Populate return message &returnDoc = &returnMsg.GetDocument(); &returnCom = &returnDoc.DocumentElement; &returnCom.GetPropertyByName("oprid").value = &oprid; &returnCom.GetPropertyByName("oprdefndesc").value = &descr;
REST URI – Resource Document http://myserver/operators/oprid=VP1 /operators/oprid={oprid} Template Mapping by element name
8) Create Routing Local-to-Local needed to use Service Operation Test utility. Any-to-Local needed to test service outside PeopleSoft.
10) Publish Web Service Integration Broker > Web Services > Provide Web Services Only need to publish if you need the WADL document.