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 create REST proxy and business services from JDeveloper and the Service Bus console.

This chapter includes the following sections:

26.1 Oracle Service Bus and REST

REST is an architecture for designing network applications. REST provides a lightweight alternative to traditional WSDL-based web services.

RESTful applications use HTTP requests to post data (create and update), get data (for example, make queries), and delete data.

26.1.1 REST Features in Service Bus

Service Bus provides the following REST support:

REST support in proxy and business services and pipelines
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 a WADL file based on an underlying WSDL (SOAP to REST) or by designing the API in the REST binding wizard.
Ability to browse and consume Oracle REST endpoints from within JDeveloper
Oracle Web Services Manager (OWSM) policy and OAuth 2 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 has been enhanced for this release to support REST natively. The previous Service Bus release provided a virtualization layer to support REST, which meant that only proxy and business services were REST-based. These REST services invoked, or were invoked by, a WSDL-based pipeline or split-join. REST proxy services converted the REST-native payload to SOAP before invoking a pipeline or split-join, while REST business services invoked by a pipeline or split-join converted the payload from SOAP to REST. The internal interface was WSDL-based, while the external business and proxy services exposed REST endpoints. In this release, REST proxy services do not have to convert REST-native payloads to SOAP; these payloads are handled natively by REST-based pipelines, without the need to be converted to or from XML.

Note:

For Native REST services, Service Bus does not automatically translate inbound responses based on the client’s HTTP Accept header. When using the REST binding, the return payload is based on the user's Accept header, unless only one type of payload is selected in the REST binding. For example, a JSON payload in $body is sent out as is (JSON) regardless of the value of the inbound request’s Accept Value header. You should use the nXSD Translate action in the pipeline to provide manual translation, as needed.

The following new native REST service types are available in this release of Service Bus:

Untyped REST proxy and business services: services for which method (operation) information may not be known at design time.
Typed REST proxy and business services: services for which method (operation) information is known at design time; method information is defined in WADL files for these services. You can provide a WADL file, or you can use the wizard to define the service’s methods and create a WADL file when you create the service. 12.1.3 REST WADL files are supported. SOA extensions, which were defined to map REST operations with WSDL, will be ignored. However, Service Bus checks any WADL used by a REST service for both syntax and semantics to make sure it conforms to the rules.
REST-based pipelines: pipelines that can be invoked by native REST proxy services. As with native REST proxy and business services, REST-based pipelines can be typed or untyped. The new REST branch node can be used in untyped REST-based pipelines or pipeline templates. See REST Branching for more information.

Note:

You cannot create a Native REST pipeline with a reference to a 12.1.3-style WADL. The WADL reference must be a native REST WADL.

Note that Service Bus also supports the REST service implementation from the 12c 12.1.3 release. These services, with WSDL-based internal interfaces, can still be created using JDeveloper. See How to Create WSDL-Based REST Services for Service Bus Using JDeveloper for more information. You can also create typed REST business services based on elements from a SOAP XML schema using the Service Bus Console.

26.1.3 Service Type Compatability of Native REST Services

Service types able to invoke or be invoked by Native REST services are described below.

Untyped REST proxy services can invoke only other native REST services (a pipeline or business service).
Typed Native REST proxy services can invoke untyped native REST services or typed REST services (pipelines or business services) with the same WADL reference.

Note:

No component (proxy, pipeline, or split join) is able to invoke native REST proxy services except Local transport proxy services.
Native REST business services can be invoked by any pipeline.

26.1.4 Payloads Supported by Native REST Services

Native REST services can send and receive payloads of the following types: JSON, XML, Form URL-encoded, Text, and Opaque.

JSON

Note:

Note that the SOAP to REST case is not considered Native REST. Services of this type support payloads of only the application/xml or application/json types.

Payloads with Content-Type application/json are considered JSON payloads and parsed accordingly into a JSON native data model. If the you were to log $body, the character data of JSON payload is wrapped with soap:Body tag, as shown in the following example:

$body = <soap-env:Body><![CDATA[{ “foo1” : “foo2”}]]><soap-env:Body>

This is not to say that JSON payload is represented as character data internally in OSB – only for the purpose of logging it is so. This is somewhat similar to the model for representation of payload with Messaging/Text service type. When JSON payload needs to be manipulated by JavaScript or action (see below), the JSON native object will be wrapped in a scriptable façade required by the JavaScript.

JSON payload are parsed and fully materialized into JSON data model objects regardless of whether a pipeline is marked for Content streaming or not.

XML, Text, and Form URL-Encoded

Native REST service type defined above will be able to receive and send payload with Content-Type

text/xml or application/xml – this is considered an XML payload.
text/plain, application/textor x-www-form-urlencoded – these are considered Text payloads.

XML payloads in Native REST binding are modeled exactly like Any XML or Messaging/XML content is modeled; the contents of $body contains inline payload XML.

Text payloads in Native REST binding are modeled exactly like Messaging/Text is modeled; the contents of $body contains inline payload character data.

When the pipeline is has content streaming enabled, Text and XML content will be handled without full materialization, the same way that AnyXML and Messaging services are handled.

Opaque (Binary)

Any Content-Type value received by the REST service other than the following is considered an opaque (or binary) payload:

application/json
application/xml
text/xml
text/plain
application/text
application/x-www-form-urlencoded

The purpose of opaque payloads is to be able to send a binary message, such as an image file, as a response from a REST proxy or as a request to a REST business service, or to receive a binary message as a response to a REST business service or request to a REST proxy. Opaque payload contents are stored in the binary repository. $body contains a reference to it using the <ctx:binary-content> element.

If you use custom media types, such as example/bookmarks+xml, you can use custom XPath functions or the Java Callout Action to covert binary to Text, XML, or JSON text.

When the pipeline has content streaming enabled, opaque payloads are processed in a streaming fashion, same as they are for a Messaging/Binary service type.

26.1.5 Response and Failure Codes for Native REST Services

You can configure a single default value for a successful response and single default value for a failure response. A status code is considered successful if it falls within the range of 200 to 300.

In the Native REST proxy service runtime, when an HTTP status code is not set in the inbound response metadata, the default successful status code, as defined in the WADL for the corresponding REST operation, is sent as the success response code. If the HTTP status code set in inbound response metadata then that status code is returned.

Similarly, in case of failure, when an HTTP status code is not set in inbound response metadata, the default failure status code, as defined in the WADL for the corresponding REST operation, is sent back to client.

For business services there are no status codes defined in the WADL created by the REST Wizard. If an existing WADL contains status codes, they are ignored by runtime. This is so that any response code can be consumed from a business service invocation.

26.1.6 Unhandled Errors and Native REST Services

When an unhandled error occurs, Native REST services return a payload back to the caller according to the already defined schema in Errors.xsd:

    <element name="RestError" type="err:RestErrorType"/>
    <complexType name="RestErrorType">
        <sequence>
            <element name="errorMessage" minOccurs="0" type="string" />
            <element name="errorCode" minOccurs="0" type="string" />
        </sequence>
    </complexType>

If the value of incoming HTTP Accept Header is application/json or null, the above payload is returned in JSON format, as shown in the following example:

    {
        "errorMessage" : "XPath can only be executed against XML or MFL content",
        "errorCode" : "OSB-395357"
    }

If the value of the HTTP Accept Header is application/xml, it will be returned in XML format. If the HTTP Accept Header value is anything other than application/json, application/xml, or null, no payload is returned. Error responses are returned with an HTTP status code of 500.

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

Services with REST endpoints can also be secured using OAuth. See Securing Services with REST Endpoints Using OAuth.

Native REST proxy services support transport-level authentication mechanisms already supported by any HTTP proxy service, such as Basic Authentication and SSL. However, message-level security is not supported.

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 Media Type Representations Supported by Typed Native REST Services

WADLs corresponding to Native REST services do not have associated type/schema information (i.e. shape of the messages) for any media type. The following list of distinct cases are supported in WADLs for this service type: JSON, XML, Text, Form URL-encoded, and Opaque (Binary).

JSON

JSON-based representation is defined by the media type application/json. It has the following representation in the WADL:

<representation mediaType=”application/json”>

At runtime, this is treated as a JSON payload, which is described in Payloads Supported by Native REST Services.

XML

The corresponding WADL representation element will have the following format:

<representation mediaType=”application/xml”> or <representation mediaType="text/xml">

The Element attribute points to the XML element. The XML schema is part of <grammars> in WADL.

At runtime, this is treated as an XML payload, which is described in Payloads Supported by Native REST Services.

Text

Text based representation is defined by the media type application/text. It has the following representation:

<representation mediaType=”application/text”> or <representation mediaType=”text/plain”>

At runtime, this is treated as a Text payload, as described in Payloads Supported by Native REST Services.

Form URL-Encoded

URL encoded representations are defined by the following representation:

<representation mediaType="application/x-www-form-urlencoded">

At runtime, this is treated as a Text payload, as described in Payloads Supported by Native REST Services.

Opaque (Binary)

Binary based representations (i.e. anything other than those listed in this section) are defined by the mediaType */*. It has the following representation:

<representation mediaType=”*/*”>

At runtime, this is treated as an Opaque payload, as described in Payloads Supported by Native REST Services.

26.2.3 Query Operations with WADL

Note:

The text in the first paragraph applies only to WADLs used by WSDL-based REST services, like the ones used by Service Bus 12.1.3.

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.

If the inbound is WSDL-based, there is no user-metadata in $inbound. However, the $outbound user-metadata still needs to be set up. In that case, transfer from inbound $body to $outbound user-metadata via a pipeline action

26.2.4 Query and Template Parameters

Query parameters are available in $inbound HTTP-specific metadata.

For inbound requests, values of template parameters are made available in the request metadata. Consider the following example:

<param name="param1" style="template" type="xsd:string"/>

At runtime, the value of the param1 template parameter is used to create the request metadata , as shown in the following example:

$inbound =  …
      <ctx:transport>
        <ctx:request>
          <headers …>
          <ctx:user-metadata name=”param1” value=”1234” />
        </ctx:request>
      </ctx:transport>

For outbound requests, the runtime looks inside $outbound metadata for template parameter values for the corresponding WADL resource/method. For example, if the WADL resource is defined as:

<resource path="/containers/{container}">

The runtime expects $outbound to contain a user-metadata element with name container and uses its value.

Additional information:

For template and query parameters in the WADL file there is no soa:expression WADL attribute as there was in Service Bus 12.1.3.
The name of the runtime property for template (path) parameters is just the parameter name.

26.2.5 Resource Method Identification

To be able to identify the resource and method, WADL has been extended to have a method identifier (name) which is unique across all resources defined in a WADL interface.

The REST Wizard UI generates a default method name which you may change. The method name is unique. A custom attribute soa:name stores this information on the method element. In this example:

<method name="POST" soa:name="create_order">

create_order is the unique method identifier.

In the Service Bus runtime, this unique identifier is mapped to the $operation system variable.

26.2.6 WADL Restrictions for WSDL-based REST Services

Only SOAP document-style WSDL documents with operations where a single part is defined by an element are supported for WSDL-based 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.7 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

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

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.

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 Resource. Click Interfaces, click WADL, and then click OK.

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:
1. Click Edit Source in the toolbar.
  
  The Edit Source dialog appears.
2. To browse to and select a new WADL file to upload, click Browse.
3. To modify the contents of the file, update the code directly in the Contents section of the dialog.
4. 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:

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, click the WADL resource to edit.

The WADL Definition Editor appears.
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.
To end the session and deploy the configuration to the runtime, click Activate.

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 Tools icon in the upper right, and then select References to find out if it has any references. In JDeveloper, right-click the WADL document and select Explore Dependencies.

To delete a WADL document:

In the Application Navigator or Project Navigator, expand the project and folders containing the WADL document to delete.
Right-click the name of the WADL document, and select Delete.

The WADL resource is deleted. A Deletion Warning icon appears when other resources reference this resource. You can delete the resource with a warning confirmation. This might result in conflicts due to unresolved references to the deleted resource.
If you are using JDeveloper, a confirmation dialog displays the number of references for the WADL document. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

26.5 Creating REST Services Using JDeveloper

You can create REST business and proxy services using JDeveloper. You can create new services using the Create REST Binding wizard in the Service Bus Overview Editor, you can expose existing WSDL services as REST, including pipelines and split-joins, or you can create REST services using the Create Proxy Service or Create Business Service wizards.

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.

You can also create REST proxy and business services from the Service Bus Console, or you can import the projects or resources containing the resources created in JDeveloper to the Console using a configuration JAR file.

A REST proxy service 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.
Any other REST-based business service or proxy service.

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 Creating Native REST Services

You can create Native REST services using JDeveloper and the Service Bus console.

Refer to the following topics to create Native REST proxy services:

Refer to the following topics to create Native REST business services:

26.5.2 How to Create WSDL-Based REST Services for Service Bus Using JDeveloper

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 can be based on a WSDL document. This maps the REST resources/verbs to internal WSDL operations and XML schemas, with incoming payloads translated to XML. 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.

See How to Create Typed REST Services for Service Bus Using JDeveloper to create a native typed REST service instead.

To create a WSDL-based REST proxy or business service in JDeveloper:

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 for 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).
Select the Service will invoke components using WSDL interfaces option.
(Optional) Select the Enforce XML Schema Ordering option to reorder JSON payloads to match the order of the elements in the XML schema. This includes inbound request payloads and responses from outbound requests.
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:
1. Double-click the default path entry of /.
  
  The Update REST Resource dialog appears.
2. In the Relative Path field, specify the resource path, and click OK.
3. To define additional resources to assign to individual operations, click the Add icon in the Resources section and repeat the above step.
Do one of the following to add and define operation bindings:
- To manually create and define operation bindings, 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) From the Configuration Shortcut section, click Add, and then 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) From the Configuration Shortcut section, click Add, and then, 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) From the Configuration Shortcut section, click Add, and then, 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.
To configure any of the bindings, do the following:
1. Double-click a binding.
  
  The REST Operation binding dialog appears.
2. 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.3 How to Create Typed REST Services for Service Bus Using JDeveloper

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. Depending on how you configure the REST binding, a proxy service can be based on an existing WADL file or you can create the WADL file when you generate the proxy service.

If you want to create a WSDL-based REST service (those used in Service Bus 12.1.3) instead, see How to Create WSDL-Based REST Services for Service Bus Using JDeveloper.

To create a native typed REST proxy or business service in JDeveloper:

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 for 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). Click Next.
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:
1. Double-click the default path entry of /.
  
  The Update REST Resource dialog appears.
2. In the Relative Path field, specify the resource path, and click OK.
3. To define additional resources to assign to individual operations, click the Add icon in the Resources section and repeat the above step.
Do one of the following to add and define methods:
- To manually create and define REST methods, from the Methods section, click the Add icon. For more information, see How to Create or Configure a REST Method in JDeveloper.
- From the Configuration Shortcut section, click Add, and then select Add resources and methods from a WADL Service to launch the WADL Chooser dialog and select an existing WADL file containing the methods to add. You can browse for a WADL file in the file system, applications, an MDS repository, and so on.
The methods appear in the Methods table.
To configure any of the methods, do the following:
1. Double-click a method.
  
  The REST Method Definition dialog appears.
2. Configure the method as described in How to Create or Configure a REST Method in JDeveloper.
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.4 How to Create or Configure a REST Operation in JDeveloper

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 step 8 in How to Create WSDL-Based REST Services for Service Bus Using JDeveloper.

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, double-click in the Style column for a parameter and select query or template from the Style list.
- To change a parameter's type, double-click in the Type column for a parameter and select a new type from the Type list.
- To enter a default value for a parameter, double-click in the Default Value column for the parameter you want to update, and enter the value to use in the Default Value field.
- To launch the Expression Builder for adding or updating an XPath expression function, double-click in the Expression column for the parameter you want to update and then click the Expression Builder icon, next to the Expression field. 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:
1. Enter a name for the fault.
2. Enter a space-separated list of HTTP statuses returned for the fault.
3. Select the type of payload for the fault. To generate a sample payload for the fault, click Generate Sample Payload.
4. Select a schema and element that defines the fault.
5. 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.5 How to Create or Configure a REST Method in JDeveloper

You can manually create REST methods and modify these methods or the ones you generated from an existing WADL. Both processes use the REST Method Definition dialog. These instructions pick up from step step 6in How to Create Typed REST Services for Service Bus Using JDeveloper.

Note:

Depending on how you created the method and whether you are creating or updating the method, some of the fields described below might not be editable.

To create or configure a REST method:

On the Create REST Service dialog, double-click a method to edit.

The REST Method Definition dialog appears.
If you are creating a new method, enter a name and an optional description.
From the Resource list, select a new resource if needed.
From the HTTP Verb list, select the HTTP method to use.
Do any of the following in the URI Parameters section:
- To view the URL that invokes the method during runtime in the Sample URL page, click Generate sample URL for method.
- To change a parameter's style, double-click in the Style column for a parameter and select query or template from the Style list.
- To change a parameter's type, double-click in the Type column for a parameter and select a new type from the Type list.
- To enter a default value for a parameter, double-click in the Default Value column for the parameter you want to update, and enter the value to use in the Default Value field.
- 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 Status fields, enter the HTTP status codes returned for a successful and a failed method.
In the Payload fields, select the type(s) of payload for the responses.
On the REST Method Definition dialog, click OK.

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

In the Application Navigator, locate the proxy service, pipeline, split-join, or business service you want to expose as a REST service.
Right-click the service, point to Service Bus, and then select Expose As REST.

The Create REST Binding wizard appears.
Optionally, modify the name of the REST service.

Tip:

The Type field cannot be modified. Because you are exposing a service, the default is Service (proxy service).

For help with the configuration fields, click Help or press F1. Help is available for all dialogs you work with in this process.
To specify that JSON payloads be reordered to match the order of elements in the XML schema, select Enforce XMLSchema Ordering.
To enter a new resource path, click the Add icon in the Resources section.
If necessary, double-click in the HTTP Verb column of the Operation Bindings section to configure the methods.
Click OK.
If the Localize Files dialog appears, clear the check box if you do not want to maintain the original directory structure, and click OK.
Do one of the following:
- Continue configuring the business service, as described in Configuring Business Services.
- Continue configuring the proxy service, as described in Configuring Proxy Services.
Click Save All in the JDeveloper toolbar.

26.5.7 What you May Need to Know About Configuring URI Parameters for REST

When you create a REST binding for 12.1.3-style, WSDL-based REST services, 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"