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