Managing REST Service Operations

This chapter discusses how to:

• Access and view REST service operations.

• Configure REST service operation definitions.

• Manage provider REST service operations.

• Manage consumer REST service operations.

• Manage REST service operation versions.

• Set compression for REST service operations.

• Rename and delete REST service operations.

Note. Before you can provide or consume services in a PeopleSoft system, you must configure the system for handling services.

See Also

Configuring PeopleSoft Integration Broker for Handling Services

Understanding Managing REST Service Operations

This section discusses:

• REST service operations.

• REST service operation types.

• REST methods.

• REST resource definitions.

• REST messages.

• Naming conventions for REST service operation metadata.

• REST service operation aliases.

• REST service operation versions.

• Monitoring service operations.

REST Service Operations

A REST service operation definition consists of general information about an operation, such as its name, description, request and response messages, and so on.

REST services operations are synchronous service operations.

Like a non-REST service operations, a REST service operation contain a routing, which determines the direction, inbound or outbound, of the service operation.

For a provider REST service operation the system creates an any-to-local routing definition when you save the service operation. You have the option to generate a local-to-local routing definition. For consumer REST service operations the system creates an outbound local-toWADL routing definition when you save the service operation. You cannot add routing definitions to provider or consumer REST service operations.

A REST service operation definition also contains a handler, which contains and runs the programming logic for providing or consuming the service operation, manipulating message content, and so on.

REST Service Operations Types

All REST service operations are synchronous service operations.

A synchronous service operations is processed in real time. Processing on the sending system does not continue until it receives a response from the receiving system.

REST Methods

REST methods determine the HTTP method for manipulating the resources defined in the service operation. The valid values are listed and described in the following table and can all be used for provider and consumer service operations:

REST Resource Definitions

REST service operation definitions contain a REST Resource Definition section where you define the REST base URL, resource URI templates, URI indexes, and document template. This section describes these REST resource definition components.

REST Base URL

The REST base URL is the common part of the URL to invoke the provider or consumer web service.

For a REST service provider this value is always the REST Target Location entry defined on the Service Configuration page for provider Service Operations. When the Provide Web Service Wizard is used to create the WADL, the option to select a secure REST target location can be selected. For provider service operations this URL is simply informational to show what would be used when the creating the complete URL(s).

The REST base URL is constructed as part of the initialization/retrieval of the service operation and uses the following format:

 <REST target Location endpoint>/< External Alias from Any to Local routing>/

For a REST consumer, the common part of the URL defined is the provider's WADL.

URI Template

Resources are constructed using URI templates. URI templates use a simple syntax where braces denote variables to be replaced when the templates are converted to actual URLs.

Note. PeopleSoft supports direct variable substitution.

The following example shows a sample URI template syntax:

weather/{state}/{city}?forecast={day} 

The denoted variables identified with the braces ( {} ) are replaced with the actual value as defined in a document template.

The system validates the string entered for the template to ensure that there is no equivalent or ambiguous defined template currently entered on the grid. Moreover the values used within the braces ( {} ) must be defined on the document template.

REST Document Template

A document template is a Document type message that you assign to the service operation. The document message has primitive elements defined with names used for value replacement within the URI template. This document can only contain primitive elements. The document cannot contain any imports (compounds). The advantage of using documents is that they cannot be inadvertently changed, as is not the case with defined record and/or fields.

Note. In the Document definition, the variables defined with the ( {} ) must be the exact name of the element name defined on the Document page, not the Tag Name defined on the XML page.

A document template is a URI on the wire with values in it.

URI Index

The system assigns an integer index value to each URI template you create for a REST service operation upon save.

You will later use these index numbers in PeopleCode to call and manipulate the associate URI template.

URI Template Validation

When you construct a URI template, you can verify the URL produced.

The REST Resource Definition URI grid features a Validate link that provides access to the Validate URI page where you can populate the URI with values from the document template and then test the link,

REST Messages

This section provides information about request and response messages used in REST service operations.

Request and Response Message Combinations

The REST method you select for a REST service operation determines the request and response message combination that you can use for the operation. The following table lists the allowable request and response message combinations for each REST method:

MIME Content-Types

When you specify a request or response message for a REST service operation, must also specify the MIME content-type of the message. PeopleSoft supports the following content types for request and response messages used for REST service operations:

• application/json

• application/xml

• text/xml

• text/plain

• text/html

Naming Conventions for REST Service Operation Metadata

The same naming convention restrictions that apply to non-REST service operations apply to REST service operations.

See Naming Conventions for Service Operation Metadata.

REST Service Operation Aliases

A service operation alias or operation alias is the service operation name that displays for the service operation when WADL is provided.

REST service operation aliases may be mixed case.

Service operation alias names for REST service operations can be the same across types. For example, you can have the same alias, for example MY_ALIAS, for Delete, Get, Put, Post and Head REST service operations.

REST Service Operation Versions

The same information about non-REST service operation versions applies to REST service operation versions.

See Service Operation Versions.

WADL Node

PeopleTools delivers a WADL node that is the default node for consumer REST services.

Monitoring REST Service Operations

You can use the same tools to monitor REST service operations as those you use to monitor non-REST service operations. These tools include:

• The Service Operations Monitor.

• The Integration Network Monitor.

• The Integration Network Transactional Tracker.

• Performance monitoring tools.

The Managing Service Operations chapter in this PeopleBook provides a brief summary of each of these tools.

See Monitoring Service Operations.

You can also find complete documentation for these tools elsewhere in PeopleBooks.

See PeopleTools 8.52: Integration Broker Service Operations Monitor PeopleBook

See Using the Integration Network Monitor.

See Using the Integration Network Transactional Tracker.

See Monitoring PeopleSoft MODULE and ACTION Information, Associating PeopleSoft Users, Modules, and Actions with DB2 UDB Threads, Monitoring Module and Action Information.

Accessing and Viewing REST Service Operation Definitions

This section discusses how to:

• Access REST service operation definitions.

• View REST service operation definitions.

Accessing REST Service Operation Definitions

Use the Service Operations component (IB_SERVICE) to access and view REST service operation definitions. The following example shows the General tab of the Service Operations component for the QE_WEATHERSTATION provider service operation:

To access a REST service operation:

1. Select PeopleTools, Integration Broker, Integration Setup, Service Operations.

   The Service Operations– Search page appears.

2. Search for a service operation definition to view.

   You can search for an operation in one of two ways:

   • Click the Search button to display all service operation definitions in the system.

   • Enter search criteria in one or more of the following fields, and then click the Search button:

     Service	Enter the service name that contains the service operation that you want to view, or click the Lookup button to search for and select a service name.
     Service Operation	Enter the name of the service operation to view, or click the Lookup button to search for and select an operation.

     Note. The Operation Type field that appears in the search box is not applicable to searching for REST service operations. The field is used only to search for non-REST service operations.

     The results of the search appear in the Service Operations results grid.

3. In the Service Operations results grid, click the name of the service operation to view.

   The Service Operations – General tab appears with data for the service operation that you selected.

Viewing REST Service Operation Definitions

The Service Operations component includes three pages:

Viewing General Service Operation Information

When you access a service operation ( PeopleTools, Integration Broker, Integration Setup, Service Operations, the Service Operations - General page (IB_SERVICE) appears.

The top portion of this page contains basic information about a service operation, including its name, description, and so on. The Service Operation Security link opens the permission list for the service. Note that the Service Operation Security link appears only after a service operation definition is saved.

The page features a REST Resource Definition section that displays the REST base URL, resources defined for the service operation, and the name of the document template associated with the service operation.

The Default Service Operation Version section displays service-operation version information and whether runtime schema validation is enabled.

The Routing Status group box shows if any-to-local or local-to-local routing definitions have been generated for the service operation. Click the Routings tab to view detailed information about routing definitions that exist for a service operation.

The Routing Actions Upon Save group box shows the possible routings that the system can generate when the service operation definition is saved.

The Message Information section displays the request message, response message information, and fault message for the service operation. The View Message links in this section open the displayed message on the Message Definition page, where you can view additional information about the message.

Viewing Handler Information

To view service operation handler information, click the Handler tab. Doing so displays the Service Operations - Handlers page (IB_SERVICEHDLR) which lists summary information about handlers that have been added to an operation.

Each REST-based provider service operation has a single handler; REST-based consumer service operations do not have handlers.

Note. There are no handlers for REST-based consumer service operations and the Handler tab does not appear when you view and work with consumer REST service operations.

The only Handler Type available for provider REST services is the OnRequest handler. When working with REST provider service operations you can implement the OnRequest handler as an application class only. The application class is implemented as any other OnRequest integration broker event.

The summary information includes the handler name, the handler type, and the implementation method for the handler. The status of the handler, active or inactive, also appears.

Click the Details link to open the Handler Details page (IB_SERVICEHDLR_SEC) for the handler. The following example shows the Handler Details page:

The Handler Details page shows additional information about the handler, including the owner and application class details.

You can also use this page to specify the handler details.

Viewing Routing Information

Click the Routing tab to open the Service Operations - Routings page (IB_SERVICERTNGS) to view a summary of routing definitions for an operation.

The Routings Definition grid on the page lists summary information for routings that are defined for a service operation. Summary information that is displayed includes the routing definition name, service operation version, routing type, sending node, receiving node, direction of the routing and the routing status.

Click a routing definition name to open the routing in the Routing Definitions component, where you can view additional information about the routing.

When you create a provider REST service operation the system automatically creates an any-to-local routing. You can also generate local-to-local routings for a provider REST service operation.

When you create a consumer REST service operation the system automatically creates a local-to-WADL routing definition. Local-to-WADL is the only routing type you can use with consumer REST service operations.

See Viewing Routing Definitions in Graphical Format.

You can also use this page to activate or inactivate routings for an operation.

See Adding Routing Definitions, Activating and Inactivating Routing Definitions.

Configuring REST Service Operation Definitions

This section discusses how to:

• Specify general service operation information.

• Manage REST resource definitions.

• Define REST service operation version information.

Specifying General Service Operation Information

To specify general service operation information:

1. Access the Service Operations-General page (PeopleTools, Integration Broker, Integration Setup, Service Operations).

2. In the Operation Description field, enter a description for the operation.

3. (Optional.) Check the User ID/ Password Required check box to require a user ID and password for inbound service operations.

   See Managing User Authentication.

4. The Security Verification drop-down list appears when you are configuring a provider service operation, and you may select the level of security with which inbound integrations must be sent. The valid options for REST based provider/inbound service operations are:

   • None.

   • SSL.

   • Basic Authentication.

   • Basic Authentication and SSL.

   Validating security on inbound integrations is described elsewhere in PeopleBooks

   See Validating Security on Inbound Integrations.

5. (Optional.) In the Operation Comments field, enter comments about the service operation.

6. (Optional.) From the Object Owner ID field, select the owner of the definition.

   The owner ID helps to determine the application team that last made a change to a service definition. The values in the drop-down list box are translate table values that you can define in the OBJECTOWNERID field record.

7. (Optional.) In the Operation Alias field, enter an alias name for the service operation.

   When working with REST service operations the service operation alias is automatically populated with the service operation name as you entered it when you created the service operation.

Managing REST Resource Definitions

This section discusses how to:

• Configure REST resource definitions.

• Validate REST URI templates.

Prerequisites for Managing REST Resource Definitions

The REST target URL must be specified on the Service Configuration – Target Locations page. The steps for defining the REST target location are described elsewhere in PeopleBooks.

See Configuring PeopleSoft Integration Broker for Handling Services.

You must have create a document type message that contains the values for any variable data you plan to use in the URI templates. For this reason you must have an understanding of PeopleSoft Documents Technology to create and manipulate document type messages.

PeopleTools 8.52: PeopleSoft Documents Technology PeopleBook

Configuring REST Resource Definitions

When you configure a REST resource definition you create one or more URI templates and assign a document template to the definition. Overviews of these topics are provided elsewhere in this chapter.

See Understanding Managing REST Service Operations.

The system auto-generates an index for each URI template that you add. You use the index the PeopleCode that you write in conjunction with the service operation.

When you configure a REST resource definition the end result is the URL that the service consumer uses to invoke the service.

The information defined in the REST resource definition is included in the WADL document that the service provider furnishes to the service consumer. The service consumer then extracts the information from the WADL document and defines it in the consumer service operation it creates for the service.

Use the REST Resource Definitions section of the Service Operations page to configure REST resource definitions. The following example shows the section:

For provider service operations the REST base URL that appears in the section is read-only. The value that appears is the value configured for the REST target location in the Service Configuration page. Information about REST base URLs and target locations is discussed elsewhere in this PeopleBook.

See REST Resource Definitions.

For consumer service operations the REST BASE URL field can be edited and must be populated with the integration provider's base URL for the service as defined in the WADL document furnished by the service provider. The following example shows the REST Resource Definition section of the Service Operations page when configuring a consumer service operation:

The page allows you to add one or more template URI strings to define one or more resources for the definition. The following example shows a REST Resource Definition configured for a provider service:

In the example shown, the QE_WEATHERTEMPLATE.v1 message contains the primitive elements to supply values for country, state, city, and day, as indicated by the following {country}, {state}, {city}, and {day} variables defined in URI templates.

The following example shows the content of the QE_WEATHERTEMPLATE.VI message where the values for the variables in the URI template are defined:

To configure a REST resource definition:

Note. When configuring consumer services the information necessary to configure the REST resource definition should be furnished to you in a WADL document by the integration partner providing the service.

1. Access the Service Operations - General page (PeopleTools, Integration Broker, Integration Setup, Service Operations).

2. Locate the REST Resource Definition section of the page.

3. Enter the REST base URL

   For provider service operations, this is a read-only field. The value populated in the field is the REST target location defined in the Service Configuration component.

4. In the Template field, enter the syntax for the URI template.

   Upon save the system auto-generates an index for the URI template.

5. To add additional URI templates, in the URI grid click the plus (+) button to add a row.

6. In the Document Template field, enter the name of the document message to associate to the definition, or click the Lookup button to search the database.

   After you select a message, you can click the View Message link to view it.

Validating URI Templates

After you construct a URI template you can verify the URL produced by using the Validate URI page (IB_SVCVERIFY_SEC). To access the page, click the Validate link next to the URI template for the URL to validate. The following example shows the Validate URI page:

The Validate URI page displays the document information and primitive elements defined in the document template specified for the REST resource definition.

The name of the URI template that is selected for validation appears in the URI Template field. In the previous example, the following URI template appears in the URI Template field and is selected for validation:

weather/{state}/{city}?forecast={day}

To validate the URI template, you click each primitive element in the document tree that corresponds to each variable in the URI template, and enter a test value for use in validation. When you click a primitive element in the document tree, the Set Value page (IB_LSTESTER_SEC) appears shown in the following example:

The Set Value page provides information about the primitive element selected to assist you in providing a useful value to test. The information that appears varies, depending on the primitive type for which you are providing a value. After you set a test value for an element, the test value appears next to the element name on the document tree.

When you have defined test values for all variables in the URI template, click the Generate URL button to generate a URL based on the test values you entered.

The following example shows the Validate URI page with test values defined for each of the variables in the weather/{state}/{city}?forecast={day} URI template. The URL field contains the generated URL.

The following example shows the complete URL generated by the system based on the test values entered:

http://buffy.us.oracle:8920/PSIGW/PSIGW/RESTListeningConnector/WeatherStation.v1/weather/Wisconsin/Washburn?forecast=Friday

Defining REST Service Operation Version Information

When you first create a service operation definition, the definition that you initially define is the default version.

When the newly created service operation definition opens, the Default check box is enabled and is read-only.

You can subsequently define additional service operation versions and assign them as the default.

See Managing Service Operation Versions.

Defining General Version Information

To define the REST service operation default version:

1. Access the Service Operations - General page (PeopleTools, Integration Broker, Integration Setup, Service Operations).

2. In the Version field, enter a version identifier.

   The default is v1.

3. (Optional.) In the Version Description field, enter a description for the operation version.

   If you enter no information, the description by default is the name of the service operation when you save the definition.

4. (Optional.) In the Version Comments box, enter comments about the version.

5. (Optional.) Check the Runtime Schema Validation check box to enable service schema validation at runtime.

Continue to the next section to specify messages for service operations. You cannot save the service operation definition until you define messages for it.

Specifying Messages for REST Service Operations

You specify messages for service operations in the Message Information section of the Service Operations – General page.

The messages that you specify define the structure of the data that is contained in the service operation.

The REST method type determines the number of messages and message types (request or response) that you specify. The possible request and response message combinations by REST method type are described elsewhere in this chapter.

See Understanding Managing REST Service Operations.

To specify messages for a REST service operation:

1. Locate the Message Information section on the Service Operations – General page.

2. Locate the Type field, and take note of the message type to define.

3. From the Status Code drop-down list, select the HTTP response code to return to the integration partner.

   The valid HTTP status code values are:

   The Status Code edit box is the actual HTTP Response code that will be returned to the Consumer. The Content-Type defines the acceptable HTTP media type.

   • 200. (Default.)

   • 201. This value is valid only when the REST method is Post.

   • 202

   • 203. This value is valid only when the REST method is Get.

   • 204

   • 205

   • 206

   • 207

4. In the Message.Version field, enter the message name followed by a dot and version, or click the Lookup button to search for one.

   After you select the message, you can click the View Message link to view the message.

5. From the Content-Type drop-down list, select the MIME content type for the message. The valid values are:

   • application/json

   • application/xml

   • text/xml

   • text/plain

   • text/html

6. Repeat steps 1 through 5 for each message type that appears in the Message Information section.

7. Click the Save button.

Specifying Fault Messages for Service Operations

You can specify fault messages for service operations for error handling.

Note the following about fault messages:

• You cannot add fault messages to asynchronous service operations.

• Fault messages must be nonrowset-based messages, container messages, or document messages. Fault messages cannot be rowset-based messages.

• The HTTP status code for fault message is 400.

To specify a fault message:

1. Locate the Default Service Operation Version section on the Service Operations – General tab.

2. Click the Add Fault Type button.

   A new row appears in which to specify a message. Note that the Type field in the new row displays Fault.

3. In the Message.Version field, enter the message name, or click the Lookup button to search for one.

   After you select the message, you can click the View Message link to view the message.

4. From the Content-Type drop-down list, select the MIME content type of the message.

   The valid values are:

   • application/json

   • application/xml

   • text/xml

   • text/plain

   • text/html

5. From the Status drop-down list, select a status code. The default and only value is 400.

6. Click the Save button.

To delete a fault message, in the Default Service Operation Version section, click the Delete Fault Type button. Then click the Save button.

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.

Managing Target Connectors for Provider REST Service Operations

Only the HTTP target connector is supported for providing REST service operations.

Managing Messages for Provider 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.

See Also

Adding Rowset, Nonrowset or Part Message Definitions

Securing Provider REST Service Operations

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.

See Validating Security on Inbound Integrations.

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.

See Setting Permissions to Service Operations.

Adding Handlers to Provider REST Services 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 this PeopleBook

See Managing Service Operation Handlers.

See Using PeopleCode to Manage REST Service Operations.

Managing Routing Definitions for Provider REST Service Operations

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 this PeopleBook.

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 this PeopleBook.

See Also

Managing System-Generated Routing Definitions

Configuring Routing Definitions

Activating and Inactivating Routing Definitions

Defining Routing Header Properties for Provider REST Service Operations

On provider REST–based service operations the any-to-local routing definition features a Header Properties tab (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.

The following example shows the Header Properties tab:

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 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

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:

1. Access the Routings-Header Properties page (PeopleTools, Integration Broker, Integration Setup, Routings and click the Header Properties tab).

2. In the Request Headers section of the page, click the plus (+) button to add a row.

3. In the Property Name field, click the Lookup button and select a property to add.

   The system adds the property to the grid.

4. In the Comments field, enter a comment about the property.

5. Repeat steps 2–4 to add additional request header properties.

6. Click the Save button.

Adding Response Header Properties

To add a response header property:

1. Access the Routings-Header Properties page (PeopleTools, Integration Broker, Integration Setup, Routings and click the Header Properties tab).

2. In the Response Headers section of the page, click the plus (+) button to add a row.

3. In the Property Name field click the Lookup button and select a property to add.

   The system adds the property to the grid.

4. In the Value field enter a value for the property.

5. In the Comment column enter a comment for the property.

6. Repeat Steps 2–5 to add additional response header properties.

7. Click the Save button.

Managing Consumer REST Service Operations

This section describes configuration tasks and considerations specific to managing consumer REST service operations. This section discusses how to:

• Add handlers to consumer REST service operations.

• Manage routing definitions for consumer REST service operations.

• Secure consumer REST service operations.

Adding Handlers to Consumer REST Service Operations

There are no handlers for consumer REST service operations. You may add connector properties to consumer service operations on the routing definition using the Routings-Connector Properties page or add them dynamically by using PeopleCode.

See Defining and Overriding Gateway and Connector Properties, Using PeopleCode to Manage REST Service Operations.

Manage Routing Definitions for Consumer REST Service Operations

The system creates a single outbound local-to-WADL node routing when you initially save a consumer REST service operation. 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.

Additional information about configuring and working with routing definitions is described elsewhere in this PeopleBook.

See Also

Managing System-Generated Routing Definitions

Configuring Routing Definitions

Activating and Inactivating Routing Definitions

Securing Consumer REST Service Operations

A PeopleSoft REST service operation provider may require that consumer services be sent secured. PeopleSoft REST providers may communicate to you that they require consumer REST service operation be secured using SSL, basic authentication, or basic authentication and SSL.

Securing Consumer REST Requests Using SSL/TLS

You can determine any SSL requirement based on the REST base URL the provider supplies and as defined on the Service Operations – General page. If the URL is a Hypertext Transfer Protocol Secure URL (HTTPS), then the provider has implemented SSL and your consumer request must also be sent using the SSL protocol. Information for setting up SSL/TLS is provided elsewhere in PeopleBooks.

See Implementing Web Server SSL/TLS Encryption.

Securing Consumer REST Requests Using Basic Authentication

If a PeopleSoft REST provider system is defined in your integration network, you can use basic HTTP authentication or PeopleSoft tokens to secure consumer requests and the PeopleSoft providing system accepts the requests as meeting the basic authentication requirement. When using PeopleSoft tokens, the system sends the token as an HTTP header property as part of the request. This behavior allows you to securely pass user credentials for proper authentication instead of using basic authentication which requires that you set an external user name and external password on the routing. If the provider has basic authentication selected for inbound security verification and no PeopleSoft token or basic authentication credentials are passed, a basic authentication pop-up window appears and the user must enter his or her credentials at that time. The PeopleSoft token option is a way to not have to prompt for user credentials for PeopleSoft-to-PeopleSoft integrations.

If a PeopleSoft REST provider is not in your integration network and the provider requires inbound basic authentication, you cannot secure the request with a PeopleSoft token. The providing system will reject such a request. You must secure the request using basic HTTP authentication.

If the consumer system is a third-party system and the provider requires inbound basic authentication, the third-party system must secure the request using basic HTTP authentication.

You specify basic HTTP authentication for a consumer outbound request on the routing definition on the Routings-Parameters page (IB_ROUTINGDEFNDOC). The Parameters section for the outbound request features a Service Operation Security link that enables you to set the security level for the outbound consumer request.

To access the Routings-Parameters page select PeopleTools, Integration Broker, Integration Setup, Routings and click the Parameters tab. The following example shows the page:

When you click the Service Operation Security link the Routing Security page (IB_ROUTINGDEFN_SEC) appears, as shown in the following example:

Use Authentication Option drop-down list to select the authentication option for the request. If you select basic authentication as the authentication option, External User ID and External Password fields appear and you must enter the external user ID and password values as furnished by the provider. The following example shows the Routing Security page when Basic Authentication is selected as the authentication option:

Keep in mind that in addition to basic authentication, the provider may require that you send the request secured by SSL.

To secure a REST consumer request using basic authentication:

1. Access the Routings-Parameters page (PeopleTools, Integration Broker, Integration Setup, Routings and click the Parameters tab).

2. In the parameters section for the outbound request, click the Service Operations Security link.

   The Routing Security drop-down list appears:

3. From the Authentication Option drop-down list, select an authentication method. The options are:

   • Basic Authentication.

     If you select this option, go to step 4.

   • None. (Default)

     If you select this option, go to step 6.

   • PeopleSoft Token.

     If you select this option, go to step 6.

4. In the External User ID field, enter the ID furnished to you by the REST provider.

5. In the External Password field, enter the password furnished to you by the REST provider.

6. Click the OK button.

See Also

Validating Security on Inbound Integrations

Managing REST Service Operation Versions

You can create and use different versions of service operations. The process for managing REST service operation versions is identical to the process for managing non-REST service operation versions.

See Managing Service Operation Versions.

Note, however, that REST resource definition are defined at the service operation level and not the service operation version level. As a result, REST resource definitions cannot be versioned.

Setting Compression for REST Service Operations

This section discusses how to:

• Set compression for provider REST service operations.

• Set compression for consumer REST service operations.

Understanding Setting Compression for REST Service Operations

PeopleSoft supports gzip and base64 (deflate) compression.

A REST service operation provider may request that inbound consumer requests be compressed using gzip or base64 (deflate) compression. The consumer is not required to send the data compressed.

The provider specifies the compression preference and the type of compression that the provider system can process on the routing definition using the Routings-Header Properties page. The compression preferences are then included in the WADL document that the provider furnishes to the consumer. The REST consumer can then view the compression preferences of the provider.

A REST service operation consumer may specify that a response from the provider be compressed using gzip or base64 (deflate) compression. The consumer specifies this request on the outbound request routing definition using the Routings-Connector Properties page. The compression requirement for the provider response is then included in the HTTP target connector headers. The REST provider can then ensure that its response meets the compression requirement of the consumer.

Setting Compression for Provider REST Service Operations

This section discusses how to set compression for Provider REST service operations.

Understanding Setting Compression for Provider REST Service Operations

You use the Routings-Header Properties page (IB_ROUTINGRESTPROP) to specify the compression method that the providing system will accept on inbound requests from a consumer, as well as the compression method the provider is using on the response to the consumer.

The two properties to use to specify message compression on the provider system are Accept-Encoding and Content-Encoding.

For provider request and response headers set compression as follows:

Setting Compression for Provider REST Service Operations

The following example shows the Routings-Header Properties page that you use to set compression for provider REST service operations. To access the page, select PeopleTools, Integration Broker, Integration Setup, Routings and click the Header Properties tab:

The previous example shows that the Request Header is set to Accept-Encoding and that the provider will accept requests that are gzip or base64 (deflate) compressed. The example shows that the Response Header is set to Content-Encoding and that the provider will send its response to the consumer base64 (deflate) compressed.

To set compression for provider REST service operations:

1. Access the Routings–Header Properties page:

   1. Select PeopleTools, Integration Broker, Integration Setup, Services and in the Existing Operations section click the name of the service operation. The Service Operations – General page appears.

   2. Click the Routings tab and in the Routing Definitions grid click the name of the routing definition. The Routing-Definitions page appears.

   3. Click the Header Properties tab.

2. Set the request header.

   In the Request Headers section:

   1. In the Property Name field click the Lookup button and choose Accept-Encoding from the list.

   2. In the Comment field enter a comment regarding the compression method the provider system will accept for the inbound request from the consumer.

3. Set the response header.

   In the Response Headers section:

   1. In the Property Name field click the Lookup button and choose Content-Encoding from the list.

   2. In the Value field click the Lookup button and choose the compression used for the response message to the consumer. The valid values arebase64 (deflate) or gzip.

4. Click the Save button.

The other options featured on the Routings-Header Properties page are discussed elsewhere in this PeopleBook.

See Defining Routing Header Properties for Provider REST Service Operations.

Defining Compression for Consumer REST Service Operations

This section discusses how to define compression for consumer REST service operations.

Understanding Setting Compression for Consumer REST Service Operations

A WADL document furnished to a REST consumer by a REST provider indicates if requests must be compressed and if so the compression method the provider system accepts. In addition, as a REST consumer you may require that responses from the provider be compressed and that the system can handle a specific compression method.

The two properties to use to specify message compression on consumer systems are Accept-Encoding and Content-Encoding.

For consumer request and response headers set compression as follows:

Setting Compression for REST Consumer Service Operations

You use the Routings-Connector Properties page (IB_ROUTINGRESTCPRP) to specify the compression method used for the outbound request and the compression method(s) the system can accept for the provider's response.

To access the Routings-Connector Properties page, select PeopleTools, Integration Broker, Integration Setup, Routings. The following example shows the page:

The previous example shows that on the REST consumer has set Content-Encoding and Accept-Encoding to base64 (deflate). By setting Content-Encoding to base64(deflate), the consumer is indicating that it is sending the consumer request to the provider base64 (deflate) compressed. By setting the Accept-Encoding to base64(deflate), the REST consumer is indicating to the REST provider that it will accept a response that is Base64 (deflate) compressed.

To set compression for consumer REST service operations:

1. Access the Routings–Connector Properties page:

   1. Select PeopleTools, Integration Broker, Integration Setup, Services and in the Existing Operations section click the name of the service operation. The Service Operations – General page appears.

   2. Click the Routings tab and in the Routing Definitions grid click the name of the routing definition. The Routing-Definitions page appears.

   3. Click the Connector Properties tab.

2. Set the request header.

   1. In the Property Name field click the Lookup button and choose Content-Encoding from the list.

   2. In the Value field click the Lookup button and choose the compression method used for the outbound request. The valid values are base64 (deflate) or gzip.

3. Set the response header.

   1. In the Property Name field click the Lookup button and choose Accept-Encoding from the list.

   2. In the Value field click the Lookup button and choose the compression method that the provider should use for the response back to the consumer. The valid values are base64 (deflate) or gzip.

4. Click the Save button.

The other options featured on the Routings-Connector Properties page are discussed elsewhere in this PeopleBook.

See Defining and Overriding Gateway and Connector Properties.

Renaming and Deleting REST Service Operations

You can rename and delete service operations using the Services Operations page in the Service Administration component. The process for renaming and deleting REST service operations is identical to the process for renaming and deleting non-REST service operations.

See Renaming and Deleting Service Operations.