Configuring Business Services using the HTTP Transport

Configuring Business Services using the HTTP Transport

You must select HTTP as the transport protocol when you configure any type of business service based on HTTP and the endpoint URI is of the form:

http://<host:port/someService>

where:

• host: is the name of the system that hosts the service.
• port: is the port number at which the connection is made.
• someService: is a target service.

Note:

You must specify the following endpoint URI when you configure a business service based on HTTPS.

Note:

https://<host:port/someService>

Table 1-2 describes all the parameters you can specify to configure HTTP transport for a business service.

Table 1-2 Parameters for Configuring HTTP Transport for Business Service

Parameter	Description
Timeout	This parameter specifies the HTTP timeout interval, in seconds, before the connection is dropped. The default value for this parameter is 0, meaning that there is no timeout.
HTTP Request Method	This parameter lets you to use one of the following HTTP methods in a request: POST – Passes all its data, of unlimited length, directly over the socket connection as part of its HTTP request body. The exchange is invisible to the client, and the URL does not change. For REST-based requests, POST tells the transport to perform a create/replace operation or perform an action with the request. GET – You can include as part of the request some of its own information that better describes what to get. This information is passed as a sequence of characters appended to the request URL in a query string. You can use GET in a business service with a Service Type of “Any XML Service,” or with a Service Type of “Messaging Service” when the Request Message Type is set to “None.” For REST-based requests, GET retrieves a representation of a remote resource. PUT – You can use PUT in a business service with a Service Type of “Any XML Service” or “Messaging Service.” PUT tells the transport to perform a create/replace operation with a REST-based request, such as uploading a file to a known location. HEAD – You can use HEAD in a business service with a Service Type of “Any XML Service,” or with a Service Type of “Messaging Service” when the Response Message Type is set to “None.” HEAD tells the transport to get header information for a remote resource rather than getting a full representation of the resource in a REST-based request. DELETE – You can use PUT in a business service with a Service Type of “Any XML Service” or “Messaging Service.” DELETE tells the transport to perform a delete operation with a REST-based request. Note: If a method is already set in the $outbound/transport/request/http:http-method variable, that value takes precedence over any method you select for HTTP Request Method.
Authentication	Select one of the following: None - Specifies that authentication is not required to access this service. Basic - Specifies that basic authentication is required to access this service. Basic authentication instructs WebLogic Server to authenticate the client using a user name and password against the authentication providers configured in the security realm, such as a Lightweight Directory Access Protocol (LDAP) directory service and Windows Active Directory. The client must send its user name and password on the HTTP request header. Basic authentication is strongly discouraged over HTTP because the password is sent in clear text. However, it is safe to send passwords over HTTPS because HTTPS provides an encrypted channel. Warning: By default, all users (authorized and anonymous) can access a business service. To limit the users who can access a business service, create a transport-level authorization policy. See Editing Transport-Level Access Policies in Using the Oracle Service Bus Console. Client Certificate - Specifies encrypted communication and strong client authentication (two-way SSL). To learn more, see Configuring Transport-Level Security in the Oracle Service Bus Security Guide.
Service Account	A service account is an alias resource for a user name and password. This is a required field if you selected the Basic Authentication Required field. For more information, see Service Accounts in Using the Oracle Service Bus Console.
Follow HTTP redirects	Select this check box to specify that HTTP redirects (which are requests with a response code 3xx) should be automatically followed. A re-direct occurs when you send an outbound request to the URL of a business service, and that service returns a response code (for example, 302) that says the URL is no longer valid and this request needs to be sent to another URL. If the Follow HTTP Redirects check box is selected, Oracle Service Bus automatically re-sends the request to the new URL without any action on your part. Deselect this check box if you do not want the HTTP redirects to be automatically followed.
Dispatch Policy	Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. For information about Work Managers, see Using Work Managers to Optimize Scheduled Work and Create Work Manager in the WebLogic Server Administration Console Online Help.
Request Encoding	Accept the default iso-8859-1 as the character set encoding for requests in HTTP transports, or enter a different character set encoding.
Response Encoding	Accept the default iso-8859-1 as the character set encoding for responses in HTTP transports, or enter a different character set encoding.
Proxy Server	Enter a proxy server resource or click Browse to choose an entry from the list of configured proxy server resources.

For more information on how to configure this transport, see Transport Configuration in Using the Oracle Service Bus Console.

REST Support

The HTTP transport provides support for working with REST (Representational State Transfer) environments through Oracle Service Bus, whether you have REST clients that need to interact with non-REST service providers, non-REST clients that need to interact with REST-based service providers, or REST-to-REST services you want to expose through Oracle Service Bus.

In a REST pattern, you invoke HTTP methods (such as GET, PUT, HEAD, POST, and DELETE) on resources that are located at specific URLs. For example, when a user updates his own profile information in a Web application that uses REST, a POST action updates the user information in the database through the service’s REST API.

Oracle Service Bus provides the following placeholder variables for handling REST-based requests for inbound and outbound communication:

• $inbound or $outbound/transport/request/http:http-method – For handling HTTP methods such as GET, PUT, HEAD, POST, and DELETE.
• $inbound or $outbound/transport/request/http:query-string – For handling query strings in a URL. For example, in the URL http://localhost:7021/myproxy/weather?operation=temperature&pincode=80439/, the query string is operation=temperature&pincode=80439.
• $inbound or $outbound/transport/request/http:relative-URI – For handling relative portions of a REST resource URL (relative to the proxy service URI). For example, in the URL http://localhost:7021/myproxy/weather, /weather is a relative URL to http://localhost:7021/myproxy.

REST in Proxy Services

With an Oracle Service Bus proxy service, you have the flexibility to interact with REST patterns, whether you are receiving REST-based requests or generating REST-based actions.

For example, if your team wants to develop REST-based applications and invoke services in a non-REST service provider, you can send REST operations through a proxy service and transform those operations into a format the service provider understands; or you could transform a non-REST request into a resource URL and invoke an operation in a REST-based service provider.

XQuery Examples

Following are XQuery examples of URI parsing using HTTP variables in a proxy server.

Relative-URI

A proxy service has a URI http://localhost:7001/weather, and you want to capture the relative URI parts of a request. You create the following XQuery:

<relative-URI>

{

for $c in

fn:tokenize($inbound/ctx:transport/ctx:request/http:relative-URI, "/")

where fn:string-length($c) != 0

return

<part>

{$c}

</part>

}

</relative-URI>

If a request comes with the URI of http://localhost:7001/weather/temperature/35457, the relative-URI will be /temperature/35457, and the XQuery output will be:

<relative-URI>

    <part>temperature</part>

    <part>35457</part>

</relative-URI>

Query-String

A proxy service has a URI http://localhost:7001/weather, and you want to capture the URL query string. You create the following XQuery:

<query-params>

{

for $c in

fn:tokenize($inbound/ctx:transport/ctx:request/http:query-string, "&amp;")

return 

<param name="{fn:substring-before($c,"=")}"

value="{fn:substring-after($c,"=")}"></param>

}

</query-params>

If a request comes with a URI of http://server:7001/weather?operation=temperature&pincode=35457, the query-string will be operation=temperature&pincode=35457, and the XQuery output will be:

<query-params>

    <param name=’operation’ value=’temperature’/>

    <param name=’pincode’ value=’35457’/>

</query-params>

REST in Business Services

With an Oracle Service Bus business service, you can invoke REST-based services.

For REST operations, the HTTP transport uses the value in the $outbound/transport/request/http:http-method variable. If that variable does not supply an HTTP method, the HTTP transport lets you select one of the following HTTP Request Methods in the transport configuration: POST, PUT, HEAD, GET, AND DELETE.

Note:

If the business service uses a Service Type of WSDL Web Service, only the POST method is available.

Using the $outbound/transport/request-http/http-method variable, you can also supply your own methods. For example, you can use COPY, MOVE, and LOCK for WebDAV environments (Web-based Distributed Authoring and Versioning).

Use the following guidelines for setting $outbound variables:

• The transport does not provide run-time validation for custom methods or for manually set supported methods that do not comply with the constraints described in this section.
• Since $outbound is only available in a Routing node, you cannot specify a method name at run time for publish and service callout actions.
• If the $outbound query-string is set, the business service passes the query string as part of the URI while invoking an external service.
• If the $outbound relative-URI is set, the business service uses that value to generate the URI, which is relative to the business service URI.

For example, in a business service with a URI of

http://service.com/purchaseOrder

and the following HTTP variables

$outbound/transport/request-http/relative-URI: “/PO12367” and
$outbound/transport/request-http/query-string: “item=NO1&color=black”

The final resolved URI is

http://service.com/purchaseOrder/PO12367?item=NO1&color=black

Response Codes for HTTP Business Services

The HTTP transport provides the following response codes for HTTP methods:

Method	Response Codes
POST	200 (OK) 201 (Created) 204 (No Content)
PUT	200 (OK) 201 (Created) 204 (No Content) 301 (Moved Permanently) – The server sends the response code. The business service handles this response by resending the original request.
HEAD, GET	200 (OK)
DELETE	200 (OK) 202 (Accepted) 204 (No Content)