26 Creating REST Services with Oracle Service Bus
This chapter describes how to integrate Representational State Transfer (REST) operations as binding components in Service Bus projects. It also describes Web Application Definition Language (WADL) documents, which are the WSDL equivalent for RESTful services.
You can only create REST proxy and business services from JDeveloper. Once you do this, you can export the REST services and then import them into the Oracle Service Bus Console if needed.
This chapter includes the following sections:
26.1 Oracle Service Bus and REST
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), and delete data. REST provides a lightweight alternative to traditional WSDL-based web services.
26.1.1 REST Features in Service Bus
Service Bus provides the following REST support:
-
REST support in proxy and business services
-
Integration with external REST APIs
-
XML, JavaScript Object Notation (JSON) with translation to and from XML, and URL-encoded data
-
JDeveloper wizard for modeling REST interfaces and WSDL mappings
-
Automatic creation of the required WADL file
-
Ability to browse and consume Oracle REST endpoints from within JDeveloper
-
Oracle Web Services Manager (OWSM) policy support for REST security
While Service Bus does not follow the Hypermedia as the Engine of Application State (HATEOAS) approach, it does support certain HATEOAS features by defining the actions in the pipeline. This includes the following capabilities:
-
Setting the HTTP link header in a REST proxy service response.
-
Reading the value of the HTTP link header in a REST business service response.
-
Overriding the endpoint URI for a REST business service request.
When you create a REST proxy service, it can be invoked from standalone REST clients. The REST business services you create can be invoked as WSDL-based services.
Note:
Service Bus does not support MIME attachments with REST, though you can return payload that contains links to attachment content.
26.1.2 REST Implementation in Service Bus
Service Bus provides a virtualization layer to support REST, which means that only proxy and business services are REST-based. These REST services invoke, or are invoked by, a WSDL-based pipeline or split-join. REST proxy services convert the REST native payload to SOAP before invoking a pipeline or split-join, while REST business services invoked by a pipeline or split-join convert the payload from SOAP to REST. The internal interface is WSDL-based, while the external business and proxy services expose REST endpoints.
Only SOAP document-style WSDL files with operations where a single part is defined by an element are supported for REST services. You can create WADL files that do not have SOAP extension annotations or do not necessarily conform to the limitations above, as long as they are syntactically valid. However, Service Bus checks any WADL used by a REST service for both syntax and semantics to make sure it conforms to the rules.
26.1.3 REST Security
REST services in Service Bus can be secured using Oracle Web Services Manager (OWSM) policies. For more information, see "Which OWSM Policies Are Supported for RESTful Web Services and Clients?" in Securing Web Services and Managing Policies with Oracle Web Services Manager.
26.2 WADL Documents for REST Services in Service Bus
When you create a proxy or business service based on the REST binding, JDeveloper automatically generates the required WADL document. The WADL file generated by the Create REST Binding wizard is based either on an existing WSDL file or a WSDL file that you create through the REST Binding wizard. It defines the structure of the service. In the runtime, Service Bus uses WADL documents to compute the relevant WSDL operation and to transform the message payload. The payload is translated from a REST media type, such as JSON, XML, or URL-encoded, into the format expected by the pipeline, and then translated back to the REST media type expected by the service. Only SOAP document-style WSDL files with operations that define a single part by an element are supported for REST services.
WADL files are saved in JDeveloper with an extension of .wadl. You can use the standard JDeveloper XML Editor to edit the WADL files you create through the REST binding wizard. A WADL file can have dependencies on one or more XML schemas.
26.2.1 WADL Documents in the Design Time and Runtime
In the design time, Service Bus uses WADL documents to define the structures for new services. In the runtime, Service Bus uses WADL documents to compute the relevant WSDL operation and to transform the message payload. The payload must be translated from a REST media type, such as JSON, XML, or URL-encoded, into the format expected by the pipeline. It then must be translated back to the REST media type expected by the service.
26.2.2 Query Operations with WADL
When configuring query-style operation parameters, you can configure expressions based on either payload or properties. Payload-based expressions, such as $msg.parameters/tns:symbol, specify values of elements or attributes of the corresponding abstract request message part. Property-based expressions, such as $property.PropertyName specify values of request metadata of the $inbound variable at runtime.
For proxy services, or inbound requests, you can query the $inbound variable in the pipeline to retrieve the values of named user-metadata elements. As an example, for $property.PropertyName, you can query the value of $inbound/ctx:transport/ctx:request/tp:user-metadata[@name = 'PropertyName']/@value. For business services, or outbound requests, you can assign values of parts of the $outbound variable in the pipeline to the corresponding request parameters.
26.2.3 WADL Restrictions
Only SOAP document-style WSDL documents with operations where a single part is defined by an element are supported for REST services. SOAP RPC-style and generic XML-style WSDL documents are not supported. This is enforced during design-time validation. For each operation or method, only element types are supported for representation. Schema types cannot be used.
26.2.4 Effective WADL Documents
As with WSDL-based services, Service Bus uses effective WADL documents in the runtime instead of the actual .wadl files you create when you develop Service Bus RESTful services. The effective WADL document represents a service's WADL properties as configured in Service Bus and also includes additional properties configured outside of the source WADL document. The effective and design-time WADL documents differ in the following ways:
-
The effective WADL document includes base URI information that contains the service endpoint URL.
-
The effective WADL document does not include the SOA extension attributes.
For more information about the difference between the design-time files and the effective files, see About Effective WSDL Documents and Generated WSDL Documents.
26.3 Creating WADL Documents
When you create a business or proxy service based on the REST binding in JDeveloper, the Create REST Binding wizard automatically generates the WADL file for the service. For more information and instructions, see Creating REST Services.
If you are using the Oracle Service Bus Console, you can create WADL documents by importing them or by creating a WADL resource and uploading an existing WADL file to the new resource
26.3.1 How to Create a WADL Resource in the Oracle Service Bus Console
This section describes uploading an existing WADL file to a new WADL resource. For more information on importing resources, see Importing and Exporting Resources and Configurations .
To create a WADL resource in the console:
-
If you have not already done so, click Create to create a new session or click Edit to enter an existing session.
-
In the Project Navigator, right-click the project or folder to contain the new WADL document, point to Create, and select WADL.
The Create WADL dialog appears.
-
Do one of the following:
-
To create the resource from an existing WADL file, click Browse next to the File Upload field and then navigate to and select the WADL file to use.
The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.
-
To create a new WADL file, or to upload the WADL file at a later time, enter a unique name for the WADL resource.
-
-
Optionally, enter a brief description of the resource.
-
Click Create.
The WADL elements, if defined, appear in the WADL Definition Editor.
-
To modify the WADL file content, do the following:
-
Click Edit Source in the toolbar.
The Edit Source dialog appears.
-
To browse to and select a new WADL file to upload, click Browse.
-
To modify the contents of the file, update the code directly in the Contents section of the dialog.
-
Click Save.
-
-
In the WADL Definition Editor toolbar, click Save.
If there are any unresolved references for the new WADL document, a Conflict icon appears next to the editor's title bar. Use the previous and next arrow buttons to scroll through any errors.
-
To end the session and deploy the configuration to the runtime, click Activate.
26.4 Modifying WADL Documents
Once you create a WADL document in a Service Bus project, you can edit or remove the document as needed.
26.4.1 How to Edit a WADL Document
WADL documents are a standard feature in JDeveloper. You can display a WADL document in a standard editor, and modify the source code directly.
If you are using the Oracle Service Bus Console, use the following procedure to edit WADL documents. You can edit the code directly or upload an updated WADL file to the resource.
To edit a WADL document in the console:
26.4.2 How to Delete a WADL Document
If any resources reference the WADL document you want to delete, remove those references before deleting the WADL resource. In the Oracle Service Bus Console, open the WADL document in the WADL Definition Editor and click the References icon in the upper right to find out if it has any references. In JDeveloper, right-click the WADL document and select Explore Dependencies.
To delete a WADL document:
26.5 Creating REST Services
You can only create REST business and proxy services using JDeveloper. You can either create new services using the Create REST Binding wizard in the Service Bus Overview Editor, or you can expose existing WSDL services as REST, including pipelines and split-joins. You can also create REST services from artifacts stored in the Oracle Metadata Services (MDS) repository, as described in Consuming Artifacts Stored in the MDS Repository.
To use REST proxy and business services in the Oracle Service Bus Console, you need to import the projects or resources from a configuration JAR file.
A REST proxy service using a WSDL SOAP 1.1 or 1.2 binding can call any of the following:
-
A WSDL-based proxy service, pipeline, split-join or business service with the same WSDL binding.
-
Any SOAP 1.1 or 1.2 binding-type proxy service, pipeline, or business service. The SOAP version must be the same as the invoking proxy service.
-
A REST business service with the same WADL reference and WSDL binding.
A REST proxy service can be invoked by REST and HTTP transport business services.
For more information about REST services and the REST Binding, see "Integrating REST Operations in SOA Composite Applications" in Developing SOA Applications with Oracle SOA Suite.
Note:
Once a REST binding has been created, do not modify the fault schema. For more information about the fault binding, see "What You May Need to Know About REST Fault Binding" in Developing SOA Applications with Oracle SOA Suite.
26.5.1 How to Create REST Services for Service Bus
When you use a REST binding to create a proxy or business service, Service Bus generates the required WADL file along with an HTTP-typed proxy or business service. The REST binding is based on a WSDL document. Depending on how you configure the REST binding, a proxy service can be based on an existing WSDL file or you can create the WSDL file when you generate the proxy service. When you create a REST business service, the wizard generates both the WSDL and WADL files.
To create a REST proxy or business service:
-
From the Components window, select Service Bus and drag a REST Binding into the Proxy Services or External Services lane in the designer.
Tip:
You can also right-click in a swimlane and select REST from the menu that appears.
The Create REST Binding wizard appears.
-
Enter a name and optionally enter a brief description of the REST service.
Tip:
For help with the configuration fields, click Help or press F1. Help is available for all dialogs you work with in this process.
-
Leave the Type field at the default value, which is selected depending on whether you are creating a proxy service (Service) or business service (Reference).
-
If you are creating a REST business service, enter the Base URI. This is the endpoint URI for the business service.
-
In the Resources section, do the following:
-
Double-click the default path entry of /.
The Update REST Resource dialog appears.
-
In the Relative Path field, specify the resource path, and click OK.
-
To define additional resources to assign to individual operations, click the Add icon in the Resources section and repeat the above step.
-
-
In the Operation Bindings section, click the Add icon and do one of the following:
-
Select Add operation binding to manually create and define a new REST operation. You can add multiple bindings. For more information, see How to Create or Configure a REST Operation
-
(Business services only) Select Add operations based on WADL service to launch the Select WADL dialog and select an existing WADL file containing the operations to implement. You can browse for a WADL file in the file system, applications, an MDS repository, and so on.
-
(Proxy services only) Select REST enable component or reference to launch the Resource Chooser and select a Service Bus component in the current application from which to generate REST operations.
-
(Proxy services only) Select REST enable external web service to launch the WSDL Chooser and select a WSDL file from which to generate REST operations. You can browse for a WSDL file in the file system, applications, an MDS repository, a UDDI registry and so on.
The operations appear in the Operation Bindings table. If you selected one of the last two options, you must configure the bindings as described in the following step. This is optional for the first two options.
-
-
To configure any of the bindings, do the following:
-
Double-click a binding.
The REST Operation binding dialog appears.
-
Configure the binding as described in How to Create or Configure a REST Operation.
-
-
Click OK on the Create REST Binding wizard.
An HTTP proxy or business service is added to the Proxy Services or External Services lane and the file is added to the project. The associated WADL file is added to the project. Both the service and the WADL file are named the same as the name you specified for the REST service in step 2.
-
To configure the new business service, see Configuring Business Services. To configure the new proxy service, see Configuring Proxy Services.
-
Click Save All in the JDeveloper toolbar.
26.5.2 How to Create or Configure a REST Operation
You can manually create REST operations and manually modify those operations or the ones you generated from existing service components or web services. Both processes use the REST Operation Binding dialog. These instructions pick up from step 6 in How to Create REST Services for Service Bus..
Note:
Depending on how you created the operation and whether you are creating or updating the operation, some of the fields described below might not be editable.
To create or configure a REST operation:
-
On the Create REST Service dialog, double-click an operation to edit.
The REST Operation Binding dialog appears.
-
If you are creating a new operation, enter a name and an optional description for the operation.
-
From the Resource list, select a new resource if needed.
-
From the HTTP Verb list, select the HTTP method to use.
-
To define the schema for the request, do one of the following:
-
Click Browse for Schema File to navigate to and select an XML schema type for the operation.
-
Click Define Schema for Native Format to launch the Native Format Builder to define a custom translation.
The Element field and the URI parameters are updated based on your selection.
-
-
Do any of the following in the URI Parameters section:
-
To view the URL that invokes the operation during runtime in the Sample URL page, click Generate URL for operation.
-
To change a parameter's style, click in the Style column for a parameter and select query or template.
-
To enter a default value for a parameter, click in the Default Value column for the parameter you want to update, and enter the value to use.
-
To launch the Expression Builder for adding or updating an XPath expression function, click in the Expression column for the parameter you want to update and then click the Expression Builder icon. Use the Expression Builder to define the XPath expression to use.
-
To manually add a parameter, click Add parameter and enter the values in the new row that appears.
-
To remove a parameter, select the row and click Delete parameter.
-
-
Click the Response tab to configure the response.
-
In the HTTP Statuses field, enter the HTTP status codes returned for a successful operation, separated by spaces.
-
In the Payload field, select the type of payload for the response.
-
To generate a sample payload that you can then save to a file, click Generate Sample Payload.
-
To define the schema for the response, do one of the following:
-
Click Browse for Schema File to navigate to and select an XML schema type for the operation.
-
Click Define Schema for Native Format to launch the Native Format Builder to define a custom translation.
The Element field and the fault bindings are updated based on your selection.
-
-
To manually add a fault binding, click Add fault binding. On the REST Fault Binding dialog, do the following:
-
Enter a name for the fault.
-
Enter a space-separated list of HTTP statuses returned for the fault.
-
Select the type of payload for the fault. To generate a sample payload for the fault, click Generate Sample Payload.
-
Select a schema and element that defines the fault.
-
Click OK.
-
-
To update a fault's HTTP statuses or payload type, double-click it in the fault binding table and update the information on the REST Fault Binding dialog.
-
On the REST Operation Binding dialog, click OK.
26.5.3 How to Expose an HTTP Proxy or Business Service as REST
In JDeveloper, you can expose an existing WSDL-based proxy service, pipeline, split-join, or business service as a REST service, which generates a proxy service and the associated WADL document. You can also expose a REST-based business service. The generated proxy service is automatically wired to the service from which it was created.
To expose a Service Bus service as REST:
26.5.4 What you May Need to Know About Configuring URI Parameters for REST
When you create a REST binding, you can use XPath expressions to define the value for the URI parameters for the operation. When you configure query-style operation parameters, the expression can either be based on payload or on a property. Expressions based on the payload, such as $msg.parameters/tns:symbol, specify values of elements or attributes of the corresponding abstract request message part. Expressions based on a property, such as $property.SomeProperty, specify values of request metadata of the $inbound variable at runtime.
For inbound requests, you can query the $inbound variable in the pipeline to get the values of named metadata elements. For outbound requests, you can assign the appropriate values of parts of the $outbound variable in the pipeline to corresponding request parameters.
26.6 Accessing WADL Documents in a Web Browser
You can view both the design-time and the effective WADL documents through a web browser. Accessing the files through a browser window displays the contents of the file in XML format. Service Bus also provides a human readable interface to make viewing the contents easier.
26.6.1 Viewing WADL Documents in XML Format
Do any of the following to view Service Bus WADL documents in a web browser.
-
To view the service effective WADL, enter the fixed HTTP URL in a web browser using the following syntax:
http://host:port/sbresource?PROXY/project_path/proxy_service_name
or
http://host:port/sbresource?BIZ/project_path/business_service_name
This works for all services for which Service Bus can generate service effective WADL documents. While there is also a WSDL document associated with this service, the above syntax displays only the service effective WADL document.
-
To view the design-time WADL document, enter the fixed HTTP URL in a web browser using the following syntax:
http://host:port/sbresource?WADL/project_path/wadl_name
26.6.2 Viewing WADL Documents in a Readable Format
You can view both design-time and service effective WADL documents in a browser using a format that is easier to read. To view the WADL document, open a web browser and enter the URL to the service as described below.
-
To view the service effective WADL document, use the following syntax:
http://host:port/sbresource?PROXY/project_path/proxy_service_name&HTML=true
or
http://host:port/sbresource?BIZ/project_path/business_service_name&HTML=true
While there is also a WSDL document associated with this service, the above syntax displays only the service effective WADL document.
-
To view the design-time WADL document, use the following syntax:
http://host:port/sbresource?WADL/project_path/wadl_name&HTML=true
The WADL content appears in the browser in a format similar to the image below.
Figure 26-1 Readable Interface for WADL Documents
Description of "Figure 26-1 Readable Interface for WADL Documents"