Managing REST Resource Definitions

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 document, 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 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:

<Provider REST target location>/< External alias from any-to-local routing>/

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

Document Template

A document template is a Document type message that define in the REST resource definition. The document message has primitive elements and collection elements defined with names used for value replacement within the URI template. This document can only contain primitive elements and collection elements. The document cannot contain any imports (compounds) or compound elements. The advantage of using documents is that they cannot be inadvertently changed, as is not the case with defined records and/or fields.

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. You define the values for the URI template variables in the REST document template.

You can define one or more URI template strings to define one or more resources for the definition

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 values as defined in the document template. In the example shown the variables are state, city and day.

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

You can build URI templates by manually entering variable strings in the template fields in the REST Resource Definition or you can use the URI Builder. Each of these methods for building URI templates is discussed later in this topic.

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.

Understanding Defining REST Base URLs

For provider service operations the system auto-populates the REST base URL. As mentioned elsewhere in the product documentation, the base URL is composed of the REST target namespace defined on the Service Configuration page and the routing alias defined on the Routings – Parameters page on the any-to-local routing for the service operation. The REST base URL takes the following format:

http://<ProviderRESTTargetNamespace>/<RoutingAlias>

For example:

http://providerserver.example.com:8010/PSIGW/RESTListeningConnector/weatherstation.v1

For consumer service operations you obtain the REST base URL from the WADL document furnished to you by the service provider. You specify the URL in the REST Base URL field in the REST Resource Definition section of the Service Operations – General page.

Specifying REST Base URLs (Provider Services)

As described previously, the REST base URL for a provider service operation is auto-populated by the system. The value populated comes from the REST target location defined on the system and the routing alias defined on the any-to-local routing definition for the service operation.

The REST base URL for a provider service operation appears in a read-only field in the REST Resource Definition section of the Service Operations – General page.

To access the Service Operations – General page select PeopleToolsIntegration BrokerIntegration SetupService Operations.

Image: REST Resource Definition (Service Provider)

This example illustrates the REST Resource Definition section on the Service Operations – General page for a provider service operation.

The example shows that the system has populated the REST base URL as described earlier in this topic.

To modify the REST base URL for a provider service operation you must change the REST target namespace defined on the Service Configuration – Target Namespace page and/or the routing alias for the any-to-local routing as defined on the Routings – Parameters page.

See Setting Target Locations for REST ServicesConfiguring Routing Definitions

Specifying REST Base URLs (Consumer Services)

The service provider furnishes service consumers the value of the base URL to define, usually in a WADL document. As the service consumer you then define this value in the REST Resource Definition section of the Service Operations – General page in the consumer service operation definition.

To access the Service Operations – General page select PeopleToolsIntegration BrokerIntegration SetupService Operations.

Image: REST Resource Definition (Service Consumer)

This example illustrates the REST Resource Definition section on the Service Operations – General page for a consumer service operation.

To specify the REST base URL for a consumer service, in the REST Base URL field enter the URL provided by the provider. The format is:

http://providerserver.example.com:8010/PSIGW/RESTListeningConnector/weatherstation.v1

Prerequisites for Using the URI Template Builder

To build a URI template using the URI Template Builder you must first define a document template in the resource definition. The document template must contain the values for the variables you plan to build out in the URI template.

Using the URI Template Builder

To access the URI Template Builder select PeopleToolsIntegration BrokerIntegration SetupService Operations. The Service Operations – General page appears. In the REST Resource Definition section of the page, click the Build link.

Image: URI Template Builder page

This example illustrates the URI Template Builder page. You can find definitions for the fields and controls later on this page.

The URI Template Builder features three sections for building a URI template:

The following fields and controls appear on this page:

Using the Validate URI Page

After you construct a URI template you can verify the URL produced by using the Validate URI page (IB_SVCVERIFY_SEC). Use the Set Value page (IB_LSTESTER_SEC) to set test values for the URL.

To access the Validate URI page select PeopleTools > Integration Broker > Service Operations and click the Validate link next to the URI template for the URL to validate.

Image: Validate URI page

This example illustrates the fields and controls on the Validate URI page. You can find definitions for the fields and controls later on this page.

The Validate URI page displays the document information and the 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 element in the document tree that corresponds to each variable in the URI template, and enter a test value for use in validation using the Set Value page.

After you assign a test value for a template, the test value appears next to the element in the document tree.

Image: Validate URI page

This example illustrates the Validate URI page. Test values defined for each variable in the URI template appear next to the variable element name.

After you enter test values click the Generate URL button to generate a URL to test.

The following fields and controls appear on the page:

Using the Set Value Page

Use the Set Value page to enter test values for URI template validation.

When you click an element in the document tree on the Validate URI page, the Set Value page (IB_LSTESTER_SEC) appears.

Image: Set Value page

This example illustrates the fields and controls on the Set Value page. You can find definitions for the fields and controls later on this page.

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.

The Element Name field displays the element name with which you're working.

In the example, the Primitive Type field and Field Length field display the data type and length as defined for the element in the document.

The name of the field where you enter a test value depends on the data type. In the previous example, the data type is a string, and therefore the system prompts you to enter a Long value.

The following table lists the possible labels for the field where you enter a test value:

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.

Validate URI Templates

To validate a URI template:

1. Access the Validate URI page ( PeopleTools > Integration Broker > Service Operations and click the Validate link next to the URI template for the URL to validate.

2. In the document tree click an element to define a test value.

   The Set Value page appears.

3. Enter a test value for the element and click the OK button.

   The Validate URI page appears.

4. Repeat step 2 and step 3 for each variable element in the URI template.

5. On the Validate URI page, click the Generate URL button.

   The URL generated based on the test values entered appears in the URL field.

6. Cut and paste the URL into a browser to test.

7. Click the Return button to return to the Service Operations – General page.

Understanding the URI Template Builder Example

The documentation in this section describes how to use the URI Template Builder page to create a URI template for the provider service QE_WEATHERSTATION using the QE_WEATHERSTATION.V1 document template illustrated throughout this topic.

This example illustrates building the following URI template:

{state,country}/WhiteSalmon

In this example:

• There is one simple string expression, {state, country}.

  This expression consists of two primitive elements.

• There is one constant, WhiteSalmon.

• The expression and constant are separated by a separator (“ / “).

Accessing the URI Template Builder

To start, access the REST resource definition for the service operation (PeopleToolsIntegration BrokerIntegration SetupService Operations. The Service Operations – General page appears).

Image: REST Resource Definition

This example illustrates the configuration of the REST resource definition before building the fourth URI template.

The service operation is currently defined with three URI templates. In this example a fourth URI template will be defined using the URI Template Builder page.

In the last row in the URI grid, click the Build link. The URI Template page appears.

Image: URI Template Builder page

This example illustrates the URI Template Builder page.

Building the Expression String for the Example URI Template

This section describes how to build the expression string {state,country}.

To build an expression string, use the Expression Workspace section of the URI Template Builder page.

Image: Expression Workspace section

This example illustrates the Expression Workspace of URI Template Builder after the expression string is built. The string appears in the expression field at the bottom of the workspace.

To build the expression string:

1. In the Expression Workspace, from the Expression Type drop-down list, select Simple String.

2. Click Primitive. and from the Primitive drop-down list, select state and click the Add button

   The {state} expression appears in the expression field.

3. From the Primitive drop-down list, select country. and click the Add button.

   The country element is added to the {state} expression. And the value in the expression field is {state,country} as shown in the previous example.

4. Click the Append to URI button.

5. In the Separator section, click the Append to URI button.

   A forward slash is added to the URI in the which now appears as {state,country}/

6. In the Constant section, enter White Salmon and click the Append to URI button.

   The constant is added to the URI and now appears as {state,country}/WhiteSalmon.

7. Under the URI string, click the Append to URI button.

   The string is added to the URI Template field and the template is complete.

Appending the Expression String to the Example URI Template

After you have created an expression you add it to the URL template.

Image: URI Template field

This example illustrates an expression string appended to the URL template. The URL Template field contains the string created in the previous section.

To append an expression from the Expression Workspace to the URL Template field, click the Append to URI button at the bottom of the Expression Workspace.

Adding a Separator to the Example URI Template

To add a separator to a URI template, click the Append to URI button in the Separator section of the URI Template Builder page.

Image: Separator section

This example illustrates the Separator section of the URI Template Builder page.

When you click the Append to URI button in this section, the system appends the value in the URI Template field with a forward slash (“/”).

Image: URI Template field

This example illustrates a separator appended to the expression string created in the previous section.

Adding a Constant to the Example URI Template

The constant to add to the URI template for this example is WhiteSalmon.

To add a constant to a URI template use the Constant section of the URI Template Builder page.

Image: Constant section

This example illustrates the Constant section of the URI Template page with a constant value entered.

When you click the Append to URI button in the Constant section, the value entered is appended to the URI template in the URI Template field.

Image: URI Template field

This example illustrates a constant appended to the URI template.

To add a constant to a URI template:

1. Enter the constant value in the Constant field.

2. Click the Append to URI button.

Validating the Example URI Template

Click the Validate button on the URI Template Builder page to access the Validate URI page to validate and test the URI template. Use the page to define test values for the variable elements in the URI template.

Image: Validate URI page

This example illustrates the Validate URI page.

The top of the page shows the document template metadata information. The tree structure shows the elements used in the document template. And the URI Template field shows the URI template to test.

In this example the URI template to test is {state,country}/WhiteSalmon. The variables in the template are those in the expression {state,country} and WhiteSalmon is a constant. Since only test values for variables are defined for testing, test values will be set for the state and country elements.

In this example the following test values are set to test the URI template:

To define test values, click an element in the document tree structure to access the Set Value page.

Image: Set Value page

This example illustrates setting the test value for the state element. The example shows that Washington has been defined for the element.

After you set a value for an element, the value appears in the document tree view on the Set Value page.

Image: Set Value page

This example illustrates that the test value Washington has been set for the state element in the document template.

After you defined test values for all variable elements in the URI template, click the Generate URL button to generate a URL to test.

Image: Validate URI page

This example illustrates the Validate URI page when all test values have been defined and the URL had been generated based on the test values.

The URL field in the previous example shows the URL generated. The complete URL is:

http://providerserver.example.com:8010/PSIGW/RESTListeningConnector/WeatherStation.v1/Washington,United%20States/WhiteSalmon

Cut and paste the URL into a browser for testing.

To validate the example URI template:

1. From the URI Template Builder page, click the Validate button.

   The Validate URI page appears.

2. Define a test value for the state element.

   1. Click the state element in the document tree.

      The Set Value page appears.

   2. In the Long field enter Washington.

   3. Click the OK button.

      The Validate URI page appears and the test value Washington appears after the state element in the document tree structure.

3. Define a test value for the country element.

   1. Click the country element in the document tree.

      The Set Value page appears.

   2. In the Long field enter United States

   3. Click the OK button.

      The Validate URI page appears and the test value United States appears after the country element in the document tree structure.

4. Click the Generate URL button

   The generated URL appears in the URL field.

5. Copy the URL to test in a browser.

6. Click the Return button to return to the URL Template Builder page.