Managing Provider REST Service Operations
This section describes configuration tasks and considerations specific to managing provider REST service operations. This section discusses how to:
Manage target connectors for provider REST service operations.
Manage messages for provider REST service operations.
Secure provider REST service operations.
Add handlers to provider REST service operations.
Manage routings definitions for provider REST service operations.
Define routing header properties for provider REST service operations.
Only the HTTP target connector is supported for providing REST service operations.
For a provider REST service operations defined with a nonrowset-based message, the Root Element field on the message definition must be populated. The root element value you specify is used for proper WADL generation.
This section discusses securing provider REST service operations.
Requiring Secured Inbound Consumer Requests
When you create provider REST services you can set the level of security with which inbound service operations must be sent using options in the Req Verification drop-down list on the Service Operations page. If you set a required inbound security level and inbound messages do not meet the requirement, the messages are rejected.
The following security levels are supported for provider REST service operations: none, SSL, basic HTTP authentication, and basic HTTP authentication and SSL.
Basic HTTP authentication.
Basic HTTP authentication and SSL.
None.
SSL.
Setting Permissions for Provider REST Service Operations
Provider REST service operations are secured using permission lists. The process for setting permissions for provider REST service operations is identical to the process for setting permissions for non-REST service operations.
The only Handler Type available for provider REST services is the OnRequest handler and the handler is implemented as an application class. The application class is implemented as any other OnRequest integration broker event.
Implementing handlers is discussed in greater detail elsewhere in the product documentation
This section discusses how to manage routing definitions for Provider REST service operations.
Working with System-Generating Routing Definitions for REST Service Operations
An any-to-local routing is always created for a provider REST service operation you initially save the service operation definition. The routing name is a system-generated name with the format ~GENERATED~<unique number>. You cannot delete this system-generated routing but you can inactivate it. You can also regenerate the any-to-local routing in the Routing Actions Upon Save section on the Service Operations-General tab. Note that if you regenerate the routing and request or response headers you have defined on the routing are deleted.
You can also generate a local-to-local routing for any REST-based service operation in the Routing Actions Upon Save section on the Service Operations-General tab. You may also inactivate local-to-local routings you create for a REST service.
Any-to-local and local-to-local routing types are discussed elsewhere in the product documentation.
See Routing Types.
You cannot create point-to-point routings for REST-based service operations.
Additional information about configuring and working with routing definitions is described elsewhere in the product documentation.
For Integration Broker, there are two properties that can be defined for a REST provider Service Operation Application Class. These two properties, when implemented, can override the Content Type and Response Code for the OnError event.
The application package: PS_PT application package,
method: IRequestHandler defines in its comments referencing these properties.
If an error occurs the OnError method, if implemented, will be automatically invoked. The type of exception can be viewed by using the Message object to retrieve the Exception object (&Message.IBException).
Please see the PeopleCode Language Reference guide for more information about the Exception class.
OnError
The return string of this method is used for a custom error message back to the Sender (if it’s not PeopleSoft). If the request was via SOAP then the string will be wrapped in a SOAP FAULT and returned. If the string itself is SOAP then it will not be wrapped but sent back as is.
Note that the return string is optional, in that if the string is null then the Integration Broker runtime will handle the error.
OnError Functioinality (REST Based Service Only)
The Response Code and Content Type will be automatically set based on the value defined for the Fault Message on the Service Operation Definition. These can be overridden by setting the property OnErrorHttpResponseCode and/or the property OnErrorContentType.
*/
interface IRequestHandler
method OnRequest(&message As Message) Returns Message;
method OnError(&request As Message) Returns string;
property integer OnErrorHttpResponseCode;
property string OnErrorContentType;
end-interface;The following example illustrates how to invoke these properties using the OnError method:
import PS_PT:Integration:IRequestHandler;
class WeatherData implements PS_PT:Integration:IRequestHandler
method WeatherData();
method OnRequest(&MSG As Message) Returns Message;
method OnError(&request As Message) Returns string;
property integer OnErrorHttpResponseCode;
property string OnErrorContentType;
/* constructor */
method WeatherData
end-method;
method OnRequest
/+ &MSG as Message +/
/+ Returns Message +/
/+ Extends/implements PS_PT:Integration:IRequestHandler.OnRequest +/
/* Variable Declaration */
....
Return &response;
end-method;
method OnError
/+ &request as Message +/
/+ Returns String +/
/+ Extends/implements PS_PT:Integration:IRequestHandler.OnError +/
Local Message &Fault_Msg;
/* Create the fault string exception based on the proper format to be sent back */
/* Override the content type and Response Code in this case
%This.OnErrorHttpResponseCode = 405;
%This.OnErrorContentType = "application/json";
Return <The fault string>;
End-If;
end-method;On provider REST–based service operations the any-to-local routing definition features a Header Properties page (IB_ROUTINGRESTPROP) where you add request message and response headers to the service operation. The headers are shown in the generated WADL document for the service operation.
To access the Header Routings page Routings-Header Properties page select and click the Header Properties tab.
Image: Routings – Header Properties page
This example illustrates the Routings – Header Properties page. The example shows the header properties for a system-generated any-to-local routing for a REST-based provider service operation.
The request and response headers that you can add are standard HTTP request and response header fields. There are several sources for addition information and descriptions of HTTP header fields. One such source is the World Wide Web Consortium (W3C).
See World Wide Web Consortium.
Note: If you regenerate a routing any header fields defined for the routing are deleted and you must recreate them.
You also use this page to define compression on provider service operations requests and responses.
See Setting Compression for REST Service Operations.
Use the LoadRESTHeaders method of the IBInfo class to load the response and request headers at runtime.
See Using PeopleCode to Manage Provider REST Service Operations.
Adding Request Header Properties
To add a request header property:
Access the Routings-Header Properties page ( and click theHeader Properties tab).
In the Request Headers section of the page, click the Add Row button (+) to add a row.
In the Property Name field, click the Lookup button and select a property to add.
The system adds the property to the grid.
In the Comments field, enter a comment about the property.
Repeat steps 2–4 to add additional request header properties.
Click the Save button.
Adding Response Header Properties
To add a response header property:
Access the Routings-Header Properties page ( and click the Header Properties tab).
In the Response Headers section of the page, click the Add Row button (+) to add a row.
In the Property Name field click the Lookup button and select a property to add.
The system adds the property to the grid.
In the Value field enter a value for the property.
In the Comment column enter a comment for the property.
Repeat Steps 2–5 to add additional response header properties.
Click the Save button.