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

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

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

Field or Control

Definition
DELETE

Delete an existing resource.
GET

Retrieve a representation of a resource.
HEAD

Identical to a GET except that no message body is returned in the response.
PATCH

Update a partial resource.
POST

Create a new resource to an existing URL.
PUT

Create a new resource to a new URL, or modify an existing resource to an existing URL.

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.

See Understanding REST Resource Definition Concepts

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:

REST Method

Request Message

Response Message

Delete

No

Yes

Get

No

Yes

Head

No

No

Patch

Yes

Yes

Post

Yes

Yes

Put

Yes

Yes

MIME Content-Types

When you specify a message for a REST service operation, you 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

HTTP Status Codes

When you define a message for a REST service operation, along with the MIME content-type, specify the HTTP response code to return to the integration partner. Note that the content-type defines the acceptable HTTP media type.

PeopleSoft supports the following HTTP status codes:

  • 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

Optional MIME Content-Types and HTTP Status Codes

Using the Set Content Types window, you can assign optional content-types and status codes to message instances on REST service operations. You can type in any content type or select from the existing content types.

Generated WADL documents will reflect the optional content-type values, allowing consumers to request the content type they prefer.

You can define optional content types on request, response, and fault message instances.

You can define optional status codes on response message instances.

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

See Naming Conventions for Service Operation Metadata.

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, Patch, Put, Post and Head REST service operations.

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

See Service Operation Versions.

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

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 topic in the product documentation provides a brief summary of each of these tools.

See Monitoring Service Operations.