Describing REST Resource Definitions

The REST Resource Definition section of the Service Operation is where you define the REST base URL, one or more URI templates, and a document template.

This information is included in the WADL document or Open API document that the service provider furnishes to the service consumer. The service consumer then extracts the information from the WADL document or Open API document and defines it in the consumer service operation it creates for the service.

This section describes REST resource definition concepts.

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.

Note: In the Document definition, the variables defined with the braces ( {} ) in the URI template 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 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

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

When building URI templates it is necessary to know these terms:

Field or Control

Description

Expression

The text between ‘{‘and ‘}’, including the enclosing braces.

Expansion

The string result obtained from a template expression after processing it according to its expression type, list of variables names, and value modifiers.

PeopleSoft supports the URI template expressions shown in the table. The table summarizes each type of template expression by its associated operator. The example expansions are based on the following variables and values:

var    :=  “value”
tools  := “tools rules!”
empty  := “”
list   := [ “val1”, “val2”, “val3” ]
path   := “/foo/bar”
x      := 1024
y      := 768

In each code example, the values in the first column are the expressions and the values in the second column are the expansions.

Expression Type

Operator

Description

Form-Style (Continuation.)

 
&

Form-style query continuation

{&x,y}          &x=1024&y=768
{&x,y,empty}    &x=1024&y=768&empty=
{&list}         &list=val1,val2,val3
{&list*}        &list=val1&list=val2&list=val3

Form-Style (Expansion.)

 
?

Form-style query expansion.

{?x,y}          ?x=1024&y=768
{?x,y,empty}    ?x=1024&y=768&empty=
{?list}         ?list=val1,val2,val3
{?list*}        ?list=val1&list=val2&list=val3

Note that the expansion process omits the equal sign ( = ) when the variable value is empty.

Fragment.

 
#

Fragment expansion with comma-separated values.

{#var}          #value
{#tools}        #tools%20rules!
{#path}/here    #/foo/bar/here
{#path,x}/here  #/foo/bar,1024/here
{#path{x}/here  #/foo/bar1024/here
{#empty}/here   #/here
{#list}         #val1,val2,val3
{#list*}        #val1,val2,val3

Label.

 
.

Label expansion, dot-prefixed

X{.var}         X.value
X(.empty}       X.
X{.list}        X.val1,val2,val3
X{.list*}       X.val1,val2,val3

Path-Segment.

 
/

Path-segments, slash-separated

{/var}          /value
(/var,empty}    /value/
{/list}         /val1,val2,val3
{/list*}        /val1,val2,val3

Path-Style.

 
;

Path-style parameters, semicolon-prefixed.

{;x,y}          ;x=1024;y=768
{;x,y,empty}    ;x=1024;y=768;empty
{;list}         ;list=val1,val2,val3
{;list*}        ;list=val1;list=val2;list=val3

Note that the expansion process omits the equal sign ( = ) when the variable value is empty.

Reserved.

 
+

Reserved expansion with comma-separated values.

{+var}          value
{+tools}        tools%20rules!
{+path}/here    /foo/bar/here
{+path,x}/here  /foo/bar,1024/here
{+path{x}/here  /foo/bar1024/here
{+empty}/here   /here
{+list}         val1,val2,val3
{+list*}        val1,val2,val3

Simple String.

NA

Simple expansion with comma-separated values.

{var}           value
{tools}         tools%20rules%21
{path}/here     %2Ffoo%2Fbar/here
{x,y}           1024,768
{var=default}   value
{list}          val1,val2,val3
{list*}         val1,val2,val3

Note the following about the operators, expressions, and expansions shown in the table:

  • The operator’s associated delimiter (“;”, “?”,”/”,”.”,”#”) is omitted when none of the listed variables are defined.

  • Multiple variables and list values have their values joined with a comma (“,”) if there is no predefined joining mechanism for the operator.

  • The operators plus ( + ) and fragment ( # ) substitute non-encoded reserved characters found inside the variables value; the other operators pct-encode reserved characters found in the variable values prior to expansion.

  • The explode modifier (“*”) indicates that the variable represents a composite value that may be substituted in full or partial forms, depending on the variables type or schema. The asterisk (“*”) indicates that just the component names and values are included in the expansion.

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 the product documentation.

See Understanding Configuring PeopleSoft Integration Broker for Handling Services.

You must have created 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.

For information on PeopleSoft Documents Technology see the product documentation for Documents Technology.