36 Integrating REST Operations in SOA Composite Applications

This section describes how to add REST support as a service binding component that connects to an Oracle Mediator or BPEL process service component. For this example, a packing and shipping service expects a shipping resource that includes information about packing and shipping an order. A shipping resource is also returned with an updated order status.

To configure the REST adapter as a service binding component in a SOA composite application:

1. Right-click the Exposed Services swimlane in the SOA Composite Editor, and select Insert > REST. This action adds REST support as a service binding component to interact with the appropriate service component.

   The Create REST Binding dialog is displayed. Table 36-1 describes the fields of this dialog.

   ---

   Table 36-1 Create REST Binding Dialog

   Field	Description
   Name	Enter a name for the REST service.
   Type	Displays the type of REST service to create (service binding component or reference binding component).
   Description	Enter a description. The description is published as part of the readable API used during deployment. The description is only available for service binding components.
   Enforce XML Schema Ordering	Select to enforce the ordering of the XML schema. When selected, this reorders JSON payloads to match the order of elements in the XML schema. This includes inbound request payloads and responses from outbound requests. This option may add a performance overload. Selecting this check box sets the REST service binding property reorderJsonAsPerXmlSchema to true in the composite.xml file.
   Resource Path	Double-click the default resources path (/) to update the resource path (this is described in Step 4) or click Add to add a new resource path.
   Operation Bindings	Click Add and select to define the REST operations based on the WSDL of the component with which the REST service interfaces. Select Add operation binding to manually define the rest service definition. You can define resource paths and REST operations. An underlying WSDL is generated that contains the mapping from the REST definition to the WSDL. For more information about this selection, see How to Generate Schemas Manually. Select REST enable component or reference to invoke the Service Explorer dialog to select the WSDL of the service component or external reference from which to map WSDL operations to resource paths and HTTP verbs. This option is only available to service binding components. This selection is described in subsequent steps of this section. Select REST enable external webservice to invoke the WSDL Chooser dialog to select a WSDL from many sources including the application server and SOA-MDS. After the WSDL is selected, the REST adapter is automatically populated with operation mappings for the selected WSDL. On completion of the dialog, a REST service, SOAP reference, and wire between the two are created.

   ---

2. In the Operation Bindings section, click the Add icon and select REST enable component or reference.

   The Service Explorer dialog is displayed.

3. Expand the navigator to select the WSDL of the service component (for this example, a BPEL process), and click OK. This action enables you to map WSDL operations to resource paths and HTTP verbs. Figure 36-1 provides details.

   Figure 36-1 WSDL Selected to Map REST Operations to Resource Paths and HTTP Verbs

   
   Description of "Figure 36-1 WSDL Selected to Map REST Operations to Resource Paths and HTTP Verbs"

   The Create REST Binding dialog is updated to appear as shown in Figure 36-2.

   The selected WSDL is read and the WSDL operation packAndShip is mapped to resource paths and HTTP verbs in the Operation Bindings section. Note that the Resource Path and HTTP Verb sections require additional configuration mapping. This is also indicated by the value of no in the Complete column.

   Figure 36-2 Create REST Binding Dialog

   
   Description of "Figure 36-2 Create REST Binding Dialog"

   The resource path and HTTP verb for each of the operations now require configuration. For this example, there is only one operation. Depending upon your WSDL, multiple operations can be displayed in the Operation column in Figure 36-2.

4. In the Resource Path table of the Resources section, double-click the default path entry of /. You can also define the resource path before starting the operation bindings. In this case, the selected resource is used for the new bindings.

   This invokes the Update REST Resource dialog.

5. In the Relative Path field, enter the resource path (for this example, /orders), and click OK. Figure 36-3 provides details.

   Figure 36-3 Update REST Resource Dialog

   
   Description of "Figure 36-3 Update REST Resource Dialog"

   Operation mappings that have the old resource path are updated with the new resource path in the Resources section and Operation Bindings section (for this example, /orders). If you are updating an existing component, all operations are typically updated. Figure 36-4 provides details.

   Figure 36-4 Resource Path Updated in Resources and Operation Bindings Sections

   
   Description of "Figure 36-4 Resource Path Updated in Resources and Operation Bindings Sections"

   You can create additional resource paths as needed by clicking the Add icon in the Resources section to display the Create REST Resource dialog.

   The HTTP Verb column of the Operation Bindings section now requires configuration.

6. In the Operation Bindings section, select an operation and click Edit or click the row (for this example, packAndShip). Figure 36-5 provides details.

   Figure 36-5 Operation Bindings Selection

   
   Description of "Figure 36-5 Operation Bindings Selection"

   The REST Operation Binding dialog is displayed.

   This dialog enables you to select the HTTP verb for the operation and populate the URI Parameters section in order to bind an HTTP verb and resource to a WSDL operation and map REST parameters to the WSDL schema of the component service. Table 36-2 describes the fields of this dialog.

   ---

   Table 36-2 REST Operation Binding Dialog

   Field	Description
   Operation	Displays the WSDL operation name that is being mapped. In most cases, you can specify a name that is used in the generated WSDL. If you selected Add operation from component service in the Create REST Binding dialog and then selected the WSDL file in the Service Explorer dialog, this field is read-only. If you selected Add operation binding in the Create REST Binding dialog, you can edit this field.
   Resource	Select an existing URL resource path from the list (this is described in Step 7) or click the Add icon to add a new resource path. The selected resource path is added to the URI Parameters table of the Request section at the bottom of this dialog. If the selected resource contains a template variable, such as {var}, the variable is added to the URI parameters.
   HTTP Verb	Select the verb to be bound to the WSDL operation (for example, GET, PUT, POST, or DELETE). (This is described in Step 8.) This selection populates the URI Parameters table with mappings from the incoming REST query parameters to the WSDL schema. The HTTP verb for the operation is also added to the Operation Bindings section of the Create REST Binding dialog after clicking OK.
   Description	Enter an optional description. Reference binding components have the Base URI field.
   Request	The Schema section displays the request schema being used. Schema URL: Displays the request schema to use. If you selected REST enable component or reference in the Create REST Binding dialog, this field is read-only because the schema is obtained from the service's operation WSDL. If you selected Add operation binding in the Create REST Binding dialog, you must browse for a schema or create a new schema from a sample using the Native Format Builder wizard. Element: Displays the element to use. The Payload section enables you to specify the format of the request payload: XML (default selection), JSON, URL-encoded, or no payload. Click Generate Sample Payload to view a sample of the selected request payload. The URI Parameters section enables you to specify the mapping from the REST query parameters to the WSDL schema. This section is automatically populated when a schema is specified (depending on the verb) in the HTTP Verb list. For GET and DELETE verbs, the parameters are bound to the WSDL schema. For POST and PUT verbs, the inbound payload is mapped to the WSDL schema. Click the Generate Sample URL for operation icon (first icon) to generate a sample URL based on all previously entered binding information. This option is typically selected after all parameters are configured. Click the Add parameter icon (second icon) to manually add a mapping parameter. In the Style column, click a specific row to invoke a list that enables you to select query or template. Template variables are typically used for POST and PUT operations. Query parameters are typically used for GET and Delete operations. In the Type column, select the data type of the parameter. All XSD primitive types are supported. In most case, when the parameter is automatically generated from a schema, the type is already set for you. If you create a new parameter, the Type column enables you to select the type from the list. In the Default Value column, you can set a default value at design time for a parameter. If a URI parameter is missing in the REST request, the corresponding default value is used by the REST service. In the Expression column, click a specific row to invoke the Expression Builder dialog for adding an XPath expression function. If there is no schema defined for an operation, the Expression Builder parameter only shows property variables and no message variables. The expression binds a parameter to a field in the WSDL schema. In all cases in which the parameter has been automatically generated (based on an existing or generated schema), this expression is already generated for you. You only add an expression if you want to add a new parameter and bind it to something else, such as a runtime property. The XPath expression specifies the location in which to insert the particular URI parameter in the normalized message.
   Response	The HTTP Statuses section enables you to specify the HTTP status code. You can enter multiple statuses, separated by spaces. For a reference, these are the possible statuses that are interpreted as successful. For a service, these are the possible successful statuses that can be returned (as set by a service component such as BPEL). The Payload section enables you to specify the possible response payloads: XML (default), JSON, or no payload. The output returned at runtime depends on the incoming requests. Click Generate Sample Payload to view a sample of the selected response payload. The Schema section displays the response schema being used if a possible payload type has been selected. If no payload has been selected, this field is not displayed. Schema URL: Displays the response schema to use. If you have not specified a schema, you can select to browse for an existing schema or create a new schema from a sample with the Native Format Builder wizard. This wizard enables you to create a schema from a JSON interchange format, XML sample, URI-encoded format, or URI sample. For more information, see How to Generate Schemas from Samples. Element: Displays the element to use. The Fault Bindings section displays the response fault name, type, status, and schema. If fault details are defined in the WSDL file, a fault binding is automatically created in this section. You can also manually define fault bindings.by clicking the Add icon. For more information about faults, see What You May Need to Know About REST Fault Binding.

   ---

7. From the Resource list, select the new resource, as needed. Figure 36-6 provides details.

   Figure 36-6 New Resource Selection

   
   Description of "Figure 36-6 New Resource Selection"

   The URI Parameters section is updated with your selection.

8. From the HTTP Verb list, select the operation (for this example, GET).

   The URI Parameters section is updated with your selection. Figure 36-7 provides details.

   Figure 36-7 HTTP Verb Selection

   
   Description of "Figure 36-7 HTTP Verb Selection"

   The style (query or template) is automatically selected in the Style column of the URI Parameters section.

   If you select or create a new REST resource that contains a template variable, Oracle JDeveloper attempts to create the template parameter with the same name. If a parameter with that name already exists, it is reused (and made into a template parameter if it was a query parameter). Duplicate parameter names are never created. You receive an error if a duplicate parameter is manually created.

9. Click the Response tab to view HTTP status code, payload output type, schema, and fault binding details. Since the schema was already defined in this example, those sections are disabled from editing.

10. Double-click the fault name to invoke the REST Fault Binding dialog. For more details about this dialog, click the Help icon or see What You May Need to Know About REST Fault Binding.

11. Edit as necessary, and click OK.

12. Click OK to return to the Create REST Binding dialog, as shown in Figure 36-8. The HTTP verb you added is displayed.

    Figure 36-8 Create REST Binding Dialog

    
    Description of "Figure 36-8 Create REST Binding Dialog"

    This example included only one operation. If your WSDL contained additional operations, they are displayed in the Operation column of the Operation Bindings section.

13. In the Operation Bindings section, select an operation and click Edit to define resources and HTTP verbs for any remaining operations.

14. Click OK to return to the SOA Composite Editor.

    The REST service is wired to the BPEL process service component. Figure 36-9 provides details.

    Figure 36-9 REST Adapter Service Wired to BPEL Process

    
    Description of "Figure 36-9 REST Adapter Service Wired to BPEL Process"

This section describes how to add REST reference binding component to a SOA composite application. This example describes how to add an existing REST reference that is based on a WADL file. WADL files provide an XML description of HTTP-based web applications.

To configure the REST adapter as a reference binding component in a SOA composite application:

1. Right-click the External References swimlane of the SOA composite application, and select Insert > REST to invoke a REST reference from a service component such as a BPEL process or Oracle Mediator.

   The Create REST Binding dialog is displayed.

2. In the Operation Bindings section, click the Add icon and select Add operations based on WADL service.

   The WADL Location dialog is displayed.

3. Specify a WADL file through one of the following methods:

   1. In the WADL URL field, specify the URL of the WADL file, then go to Step 4.

      or

   2. Click the Search icon to invoke the WADL Chooser dialog for selecting the WADL file. Options are provided for finding WADLs in the local file system or project, in the design-time Oracle Metadata Services Repository (MDS Repository), or by connecting to an application server to find WADLs associated with deployed Oracle SOA Suite or Oracle Service Bus services. Figure 36-10 provides details.

      Figure 36-10 WADL Chooser Dialog

      
      Description of "Figure 36-10 WADL Chooser Dialog"

   3. Select the WADL file, and click OK.

   4. Go to Step 4.

4. Click OK.

5. Select copy schema artifacts into the project to copy schemas referenced in the WADL file to the local project because they are used by the new REST adapter reference. This is the recommended method.

6. See the step based on the type of WADL file selected. Table 36-3 provides details.

   ---

   Table 36-3 WADL File Status

   If the Selected WADL File Was Provided By...	Then...	See Step...
   An Oracle SOA Suite or Oracle Service Bus REST service	The Create REST Binding dialog is completely configured with information from the WADL file. All operations, resource paths, and verbs are displayed in the Operation Bindings section. A complete configuration is indicated by a value of yes in the Complete column of the Operation Bindings section.	6.a
   A non-Oracle SOA Suite or Oracle Service Bus REST service such as a Jersey service.	The WADL Parsing Issues dialog indicates that additional configuration is required.	6.b

   ---

   1. View the Create REST Binding dialog and its contents, and click OK. Figure 36-11 provides details.

      Figure 36-11 Create REST Binding Dialog with All Operational Bindings Complete

      
      Description of "Figure 36-11 Create REST Binding Dialog with All Operational Bindings Complete"

   2. Review the list of recommended corrective actions in the WADL Parsing Issues dialog shown in Figure 36-12, then click OK. The same information is written to the Oracle JDeveloper Log window for later reference.

      A WADL file for a non-Oracle SOA Suite or Oracle Service Bus service typically does not include all required information. You must manually complete configurations. In many cases, such as in Figure 36-12, the WADL file used does not supply the schemas required to bind the REST reference to a WSDL operation. The schemas can often be generated using the Native Format Builder wizard using a sample payload provided by the REST service provider.

      Figure 36-12 WADL Parsing Issues

      
      Description of "Figure 36-12 WADL Parsing Issues"

      The Create REST Binding dialog is displayed.

      For a REST binding that requires further configuration, a value of no is displayed in the Complete column of the Operation Bindings section. Tool tips in the Complete column for each no value identify what is missing so that you can perform corrective actions. The OK button is disabled as long as at least one operation has a value of no in the Complete column. Figure 36-13 provides details.

      Note:

      All error and warnings are also displayed in more detail in the Log window in Oracle JDeveloper. For example, the Log window contains entries such as the following:

      ERROR at [resource path: containers/{container}, method name: PUT,
      request/response: response, representation mediaType:
      application/xml ] - No schema information is available for
      containers/{container}.PUT response.  Please specify a schema.
      

      Figure 36-13 Create REST Binding Dialog with Incomplete Operational Bindings

      
      Description of "Figure 36-13 Create REST Binding Dialog with Incomplete Operational Bindings"

   3. Perform the corrective actions indicated by the tool tips. When configuration has been successfully completed, a value of yes is displayed for all operations in the Complete column of the Operation Bindings section. Figure 36-14 provides details.

      Figure 36-14 Create REST Binding Dialog with All Operational Bindings Complete

      
      Description of "Figure 36-14 Create REST Binding Dialog with All Operational Bindings Complete"

      For more information about the SOA design-time MDS Repository, see Managing Shared Data with the Design-Time .

If you do not have a schema or sample data to generate a schema, you can manually enter the parameters for which to generate a schema. To manually define a schema, click the Add icon, and select Add operation binding in the Operation Bindings section of the Create REST Binding dialog.

Note the following guidelines:

• In the URI Parameters section of the REST Operation Binding page, enter the necessary query or template parameters. You can select a data type for each parameter, but you do not need to enter an expression. If there is no schema and payload specified, when you click OK, the parameter schema is automatically generated (embedded in the WSDL). Parameters that have an expression that is mapped to a runtime property are not included in the generated schema.

• If there is no schema defined for an operation, the Expression Builder dialog that is accessible from the Expression column only shows property variables and no message variables.

For complete instructions about creating REST support, see How to Configure the REST Adapter as a Service Binding Component in a SOA Composite Application and How to Configure the REST Adapter as a Reference Binding Component in a SOA Composite Application.

You can generate schemas from sample files, including JSON interchange format.

For complete instructions about creating REST support, see How to Configure the REST Adapter as a Service Binding Component in a SOA Composite Application and How to Configure the REST Adapter as a Reference Binding Component in a SOA Composite Application.

You can assign global token variables for the host name, port number, and protocol in the Base URI field of the Create REST Binding dialog.

To use global token variables:

Normalized message properties are available for certain standard HTTP headers. These properties are displayed for selection in the Properties tab of receive and reply activities in a BPEL process in Oracle JDeveloper, as shown in Figure 36-23. These header properties are not propagated by default across the service engines. You must manually propagate them by providing the appropriate assignment logic.

Figure 36-23 Normalized Message Properties in Receive and Reply Activities

Description of "Figure 36-23 Normalized Message Properties in Receive and Reply Activities"