This chapter includes the following sections:
Creating REST Support in Service and Reference Binding Components
Testing and Configuring REST Reference Binding Components in
For more information about using a REST adapter, see "Defining a Shipping Resource with a REST Service" of Understanding Oracle SOA Suite.
REST is an architecture for designing network applications. RESTful applications use HTTP requests to post data (create and update), get data (for example, make queries), update data, and delete data. REST provides an alternative to using web services.
Oracle SOA Suite provides the following REST support:
Support in SOA composite applications:
Enable REST support in new or existing services.
Integrate with external REST APIs.
Orchestrate a set of RESTful state transitions (RPC/Hypermedia as the Engine of Application State (HATEOAS) approach).
Support for XML, JavaScript Object Notation (JSON) (with automatic translation to and from XML), URI sample, and URL-encoded GET/POST data.
Generation of sample URI for REST service operations.
Support for WADL services. The WADL can be provided by a deployed Oracle SOA Suite or Oracle Service Bus service or a non-Oracle SOA Suite or Oracle Service Bus service such as a Jersey REST service.
Ease of development:
Oracle JDeveloper wizard provides several options for modeling REST interfaces and WSDL operation bindings:
Manually define resource paths and REST operations to generate an underlying WSDL that contains the mapping from the REST definition to the WSDL.
Select the WSDL of the service component or external reference from which to map WSDL operations to resource paths and HTTP verbs.
Select a WSDL from many sources (for example, the application server or SOA-MDS) from which to automatically populate the REST adapter with operation mappings.
Readable API that publishes each method used upon deployment.
Ability to browse and consume Oracle REST endpoints (including Oracle Service Bus) from within Oracle JDeveloper.
Oracle Web Service Manager (OWSM) policy support for REST security.
Support for the following use cases:
Get a list of customers
Create a new customer
Get customer details
Update customer details
Delete a customer
Create a new address for a customer
Get an address of a customer
Update the address of a customer
Oracle SOA Suite components, services, and reference can be selected and exposed as a REST service. This section describes how to perform the following tasks:
Add REST support as a service binding component in an existing SOA composite application
Add REST support as a reference binding component that can be invoked from a SOA composite application
Configure REST support through shortcuts
Generate REST schemas
Use global token variables for host, port, and protocol values
Note:
You cannot attach a REST binding to an asynchronous component (for example, an asynchronous BPEL process). If you attempt this attachment, a message is displayed that indicates this is not supported and suggests a workaround of placing an Oracle Mediator between the REST adapter and the service that has a one-way interface and routing the service callback to another (outbound) REST adapter service.
You cannot connect a REST service binding component to a REST reference binding component.
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:
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 |
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.
|
In the Operation Bindings section, click the Add icon and select REST enable component or reference.
The Service Explorer dialog is displayed.
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
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.
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.
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.
In the Relative Path field, enter the resource path (for this example, /orders
), and click OK. Figure 36-3 provides details.
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
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.
In the Operation Bindings section, select an operation and click Edit or click the row (for this example, packAndShip). Figure 36-5 provides details.
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.
|
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.
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.
|
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.
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. |
From the Resource list, select the new resource, as needed. Figure 36-6 provides details.
The URI Parameters section is updated with your selection.
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.
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.
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.
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.
Edit as necessary, and click OK.
Click OK to return to the Create REST Binding dialog, as shown in Figure 36-8. The HTTP verb you added is displayed.
This example included only one operation. If your WSDL contained additional operations, they are displayed in the Operation column of the Operation Bindings section.
In the Operation Bindings section, select an operation and click Edit to define resources and HTTP verbs for any remaining operations.
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
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:
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.
In the Operation Bindings section, click the Add icon and select Add operations based on WADL service.
The WADL Location dialog is displayed.
Specify a WADL file through one of the following methods:
In the WADL URL field, specify the URL of the WADL file, then go to Step 4.
or
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.
Select the WADL file, and click OK.
Go to Step 4.
Click OK.
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.
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. |
|
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. |
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
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.
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
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
For more information about the SOA design-time MDS Repository, see Managing Shared Data with the Design-Time .
You can configure the REST adapter through several shortcuts based on WSDL or WADL files.
From the Oracle JDeveloper main menu, select Window > Application Servers.
Right-click a WSDL service and select SOA > Expose as REST. Figure 36-15 provides details.
Figure 36-15 Automatic REST Adapter Service Binding Component Configuration
The Create REST Binding dialog is invoked and prepopulated with operation mappings from the selected WSDL file.
Complete any necessary configuration by following the procedures in How to Configure the REST Adapter as a Service Binding Component in a SOA Composite Application.
Note:
You are prompted to make a local copy of the selected WSDL and its dependent artifacts. If you select to make a local copy, the binding.ws
section for the SOAP reference binding component contains the original concrete WSDL/endpoint location that was selected and the copied WSDL is used as the abstract WSDL (in the composite import, and so on).
When configuration is complete, a REST service binding component is wired to a SOAP reference binding component. Figure 36-16 provides details.
Figure 36-16 REST Service Binding Component and SOAP Reference Binding Component Configuration
From the Oracle JDeveloper main menu, select Window > Application Servers.
Right-click a REST/WADL service and select SOA > Generate REST Reference. Figure 36-17 provides details.
Figure 36-17 Automatic REST Adapter Reference Binding Component Configuration
The Create REST Binding dialog is invoked and prepopulated with information from the selected WADL file.
Complete any necessary configuration by following the procedures in How to Configure the REST Adapter as a Reference Binding Component in a SOA Composite Application.
When configuration is complete, a REST reference binding component is displayed, as shown in Figure 36-18.
Figure 36-18 REST Adapter Reference Component
In the SOA Composite Editor, right-click a SOA component service or an external reference, and select the Expose as REST option. Figure 36-19 provides details.
The Create REST Binding dialog is invoked and prepopulated with information from the selected WADL file.
Complete any necessary REST adapter configuration.
When configuration is complete, REST support (for this example, a service binding component) is created and automatically wired to the interface on which you clicked. Figure 36-20 provides details.
Figure 36-20 REST Adapter Service Binding Component
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
For inbound cases in which an external client is interacting with a SOA REST service, you can configure the service to send a hyperlink to the next resource with which the client interacts. This hyperlink can be sent in the payload of the response or the HTTP link response header. The following normalized message properties build and return the next link:
rest.binding.requestBaseURI
This property is available on the request message. It holds the base URI of the REST service. In the SOA composite application, this can be combined with the path of another resource in the same REST service to build an absolute URL linking back to that resource.
rest.binding.http.Link
When this property is set on the response message, a link header is added to the HTTP response. The value of this header is the value of the normalized message property.
For outbound cases in which the SOA composite application is invoking an external REST service, the service may return a response with the next link either in the link header or the payload. The following normalized message properties are available to help get the next link and invoke the resource located at that link:
rest.binding.http.Link
If the HTTP response from the external REST service contains a link header, a rest.binding.http.Link property is added to the response message. The value of this property is the value in the link header.
rest.binding.requestURI
The resource located at the next link can be invoked by setting the rest.binding.requestURI property on the request message. If set, the URL in this property overrides the URL provided at design time. It invokes the external REST service.
There are several preconditions that must be satisfied when a SOA composite application is invoking REST resources based on the next link it receives from the external REST service:
The potential resources that can be invoked must be designed in the REST reference binding component at design time.
The structure of the request and response must be known and modeled at design time.
For information about setting normalized message properties in the Properties tab, see Propagating Normalized Message Properties Through Message Headers.
REST services and references are capable of handling custom HTTP headers. Table 36-4 provides details.
Table 36-4 Custom Header Support
Direction | Service Side | Reference Side |
---|---|---|
Request |
Any HTTP headers that come in the request are propagated as normalized message properties. The headers are appended with rest.binding.http.header-name. These headers are available in the service engine as part of normalized message properties. For example, any individual header can be obtained with the BPEL process in the receive and reply activity properties. |
All normalized message properties prefixed with rest.binding.http.* are added as HTTP headers to the HTTP request. The REST service removes the prefix rest.binding.http. from the header name. before attaching the headers to the HTTP request. |
Response |
All normalized message properties prefixed with rest.binding.http.* are added as HTTP headers to the HTTP response. The REST service removes the prefix rest.binding.http. from the header name before attaching the headers to the HTTP response. |
Any HTTP headers coming in the response are propagated as normalized message properties. The headers are appended with rest.binding.http.header-name. These headers are available in the service engine as part of normalized message properties. For example, any individual header can be obtained with the BPEL process in the receive and reply activity properties. |
You define REST fault binding response details in the REST Fault Binding dialog, as shown in Figure 36-24. If fault details are already defined in the WSDL file, a fault binding is automatically created in the Fault Bindings section of the REST Operation Binding dialog. You can also manually define fault bindings.by clicking the Add fault binding icon in the Fault Bindings section.
By default, the fault status is 400 when there is a fault payload and 404 when there is no fault payload.
Fault binding details are based on your selection in the Create REST Binding dialog:
If you selected REST enable component or reference, fault bindings are automatically generated based on faults defined in the WSDL file.
If you selected Add operation binding, you must configure the fault bindings to be supported, which are added to the WSDL being generated.
The Fault Bindings section of the REST Operation Binding dialogs shows the response fault name, type, status, and schema. Figure 36-25 provides details.
You can select to create a REST schema from a JSON interchange format sample in the Choose Type dialog of the Native Format Builder wizard, as shown in Figure 36-22. During schema generation, the wizard attempts to do the following:
Generate a REST schema with no namespace information
Consume a JSON interchange format sample with no namespace information and generate an XML with the correct namespaces
However, there are several cases in which the conversion cannot be handled.
Namespace information is retained to enable the JSON interchange format sample shown in [[LinkToOldExample - TopicID=SOASE88875 - Title=Unsupported JSON Interchange Format ]] to be converted. This is because the underlying schema has elements and attributes from multiple namespaces.
[[OldExample - - TopicID=SOASE88875 - Title=Unsupported JSON Interchange Format ]]
<schema xmlns:us="http://xmlns.oracle.com/addresses/us" xmlns:india="http://xmlns.oracle.com/addresses/india" targetNamespace="http://xmlns.oracle.com" xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <import ...> <element name="Person"> <complexType> <choice> <element ref="us:Address"/> <element ref="india:Address"/> </choice> </complexType> </element> </schema> <schema targetNamespace="http://xmlns.oracle.com/addresses/us" xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <element name="Address"> <complexType> <sequence> <element name="Street" type="xsd:string"/> <element name="City" type="xsd:string"/> <element name="State" type="xsd:string"/> <element name="ZipCode" type="xsd:integer" minOccurs="0"/> </sequence> </complexType> </element> </schema> <schema targetNamespace="http://xmlns.oracle.com/addresses/india" xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <element name="Address"> <complexType> <sequence> <element name="Street" type="xsd:string"/> <element name="City" type="xsd:string"/> <element name="District" type="xsd:string" minOccurs="0"/> <element name="State" type="xsd:string"/> <element name="PinCode" type="xsd:integer" minOccurs="0"/> </sequence> </complexType> </element> </schema>
Sibling elements with duplicate names under a sequence group element cannot be converted because this translates to an object with duplicate keys in JSON, which is not valid.
The SOAIncomingRequests_maxThreads property by default is configured based in the SOADataSource data source in Oracle WebLogic Server Administration Console. This setting may be not enough for REST services under a heavy load (for example, if you have 200 concurrent users in a scenario in which a REST reference is calling a REST service within the same node). You must increase the SOAIncomingRequests_maxThreads value to 400
to avoid the exception error shown in [[LinkToOldExample - TopicID=SOASE88877 - Title=Exception Error When REST References Call REST Services ]].
[[OldExample - - TopicID=SOASE88877 - Title=Exception Error When REST References Call REST Services ]]
<May 2, 2014 10:16:11 AM PDT> <Error> <oracle.soa.bpel.system> <BEA-000000> <cube engineJTA transaction is not in active state. The transaction became inactive when executing activity "" for instance "30,023", bpel engine can not proceed further without an active transaction. please debug the invoked subsystem on why the transaction is not in active status. the transaction status is "MARKED_ROLLBACK". The reason was The execution of this instance "30023" for process "BuyCoffeeBPELProcess" is supposed to be in an active jta transaction, the current transaction status is "MARKED_ROLLBACK", the underlying exception is "Service Unavailable" . Consult the system administrator regarding this error. , Cikey=30023, FlowId=20014, Current Activity Key=30023-BpInv0-BpSeq0.3-3, Current Activity Label=InvokeCreateOrder, ComponentDN=default/CoffeeShopClient!1.0*soa_19d4a881-115b-42c5-824d-1af3fa766 62d/BuyCoffeeBPELProcess oracle.fabric.common.FabricInvocationException: Service Unavailable at . . . . . .
You can test the REST adapter with the HTTP Analyzer.
To test the REST adapter with the HTTP Analyzer:
You can initiate instances of SOA composite applications that include REST binding components from the Test Instances page in Oracle Enterprise Manager Fusion Middleware Control. This page enables you to test any WSDL or WADL. For more information, see Section "Initiating a SOA Composite Application Test Instance" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
You can configure properties for REST reference binding components in Oracle Enterprise Manager Fusion Middleware Control. For more information, see Section "Configuring Properties for REST Adapters" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.