Defining REST Service Operation Version Information

This section discusses how to:

  • Define default REST service operation versions.

  • Define message instances for REST service operations.

  • Define fault messages for REST service operations.

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.

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 check box, enter comments about the version.

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

  6. (Optional.). In the Routing Actions Upon Save box, check the Generate Local-to-Local routing box to generate the routing when you save the service operation definition.

    Note that the Any-to-Local box is read-only and selected by default and an any-to-local routing is created upon save.

    This box only appears when working with provider service operations.

    More information about routing definitions for provider REST services is available in the product documentation.

    See Managing Provider REST Service Operations

When working with REST provider service operations a

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

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

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

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

  5. (Optional) Define optional content-types.

    To define optional content-types:

    1. Click the Optional Content-Types link.

      The Set Content Type page appears.

    2. From the Content-Type drop-down list, select a content type.

      The valid values are the same as those listed in Step 4.

    3. To add additional content-types, click the Add Row button (+) and select a content-type from the list.

    4. Click the OK button.

      The Service Operations – General page appears.

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

    Note that the content-type defines the acceptable HTTP media type.

    The valid HTTP status code values are:

    • 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

  7. (Optional) Define optional status codes.

    You can defined optional status codes on response messages only.

    Tp define optional status codes:

    1. Click the Optional Status Codes link.

      The Set Status Codes page appears.

    2. From the Status Code drop-down list, select a status code.

      The valid values are the same as those listed in Step 6.

    3. To add additional status codes, click the Add Row button (+) and select a status code from the list.

    4. Click the OK button.

      The Service Operations – General page appears.

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

  9. Click the Save button.

This section describes how to specify fault messages for REST service operations.

Understanding Fault Messages for REST 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.

Understanding Fault Message HTTP Return Status Codes for REST Service Operations and the OnError Method

The system recognizes and uses fault message HTTP status codes only if the fault Message is used in the OnError method. Simply using the fault message within the OnRequest method will be treated like any other message.

Understanding Fault Message HTTP Return Status Codes and Service System Status for Provider REST Service Operations

If you specify fault messages for provider REST service operations, the service system status impacts the HTTP return status codes as follows:

Field or Control

Definition
Production

If the service system status is set to Production any errors by the framework or that are not part of a fault message defined in the OnError method will result in an HTTP status code returned of 500 with the errors not included in the payload.

If a fault message is defined on the service operation and invoked within the OnError method then the status code of 400 (or any other status code set for the fault) will be returned as the HTTP status code along with the error message.
Development

If the service system statu is set to Development any errors by the framework or that are not part of a fault message defined in the OnError method will result in an HTTP status code returned of 500 with the error message included in the payload.

If the fault message is defined on the service operation and invoked within the OnError method then the status code of 400 (or any other status code set for the fault) will be returned as the HTTP status code along with the error message.

Defining Fault Messages for REST Service Operations

To define a fault message for a REST service operation:

  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. (Optional) Define optional content-types.

    To define optional content-types:

    1. Click the Optional Content-Types link.

      The Set Content Type page appears.

    2. From the Content-Type drop-down list, select a content type.

      The valid values are the same as those listed in Step 4.

    3. To add additional content-types, click the Add Row button (+) and select a content-type from the list.

    4. Click the OK button.

      The Service Operations – General page appears.

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

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