Using a REST-based Service
You can create web service interaction activities in BPEL that can handle messages based on the Representational State Transfer (REST) architecture rather than WSDL operations. This means that you do not need your own WSDL file in order to create certain types of BPEL processes. You can simply instantiate a process with a request that looks like the following example:
http://localhost:8080/active-bpel/services/REST/lookUpWeather/mass/waltham
REST is a style of architecture for describing how resources are defined and addressed on systems such as the World Wide Web. Using REST, you can send and receive REST-based messages over HTTP without an additional messaging layer such as SOAP.
You can also access partner REST services from a BPEL process.
The idea of REST is that clients and services can communicate over HTTP to exchange representations of resources. A resource is any item of interest, made accessible through some URL on the network. In BPEL, a representation is an XML document with optional attachments of a different content type.
A BPEL process can send and receive a REST request. When a REST request is sent to the process, Process Server converts it to a standard WSDL message. When the process invokes a REST service, a standard WSDL message is converted into a REST request. The response is a document representing the requested resource. The document type returned is defined by the Content-Type header of the HTTP response.
To get started with REST, you need the following:
- •A BPEL project that imports aeREST.wsdl and aeREST.xsd
- •For invokes you need:
- - The URL of the REST resource you will address
- - The HTTP method you want to invoke
- - The content type of the resource representation you will return
- - For XML content returned, an optional schema for the returned message (for example, atom schema, vender specific) to address the content within the BPEL process
- - The query parameters specified by the REST service you want to address
See Also:
Creating a REST-based Receive or Invoke
In a REST-based service, you can create a start activity (receive, pick, event handler) that executes the URL request that is submitted through the address field of a Web browser or an HTTP client. You can also create an invoke activity that sends a request to a web-based service via HTTP.
The receive and invoke activities must be based on a WSDL file named aeREST.wsdl. The port types and partner link types for this WSDL are in the System Services tree in the Interfaces dialog in Participants view.
In essence, the WSDL defines the RequestResponse operation and messages for receiving and sending REST requests. Process Developer converts an incoming REST request to a WSDL message and does the reverse for an outgoing request.
A request that targets a REST-based process looks like the following example:
http://localhost:8080/active-bpel/services/REST/lookUpWeather/mass/waltham
REST Request Message
Process Server converts the request to an input message that would have the following parts, shown in the example:
RestRequest example (Not all elements are shown. See the table below):
<?xml version="1.0" encoding="UTF-8"?>
<ns2:RESTRequest xmlns:ns2="http://schemas.activebpel.org
/REST/2007/12/01/aeREST.xsd">
<ns2:subdomain>Search</ns2:subdomain>
<ns2:method>GET</ns2:method>
<ns2:pathInfo>V1</ns2:pathInfo>
<ns2:params>
<ns2:param name="temp" value="50"/>
<ns2:param name="windchill" value="40"/>
</ns2:params>
<ns2:payload contentType="text/xml">lookUpWeather/mass/waltham?temp=50&windchill=40</ns2:payload>
</ns2:RESTRequest>
The message parts are defined as follows:
subdomain | Optional for partner service (invoke). The part that identifies one of the REST-based services that a domain can offer. For example Yahoo offers search, news, and other services. You can use the subdomain part to specify the service you want to use. In the endpoint reference for the partner link, you can add a logical subdomain value that can be replaced by the subdomain specified: <WS-Address>nnnn.yahooapis.com</WS-Address>. |
method | The HTTP method to execute. See the HTTP Methods table below. |
pathInfo | Optional for partner service (invoke). Parts that extends the resource details defined in WS-Address. For example, in search.yahooapis.com, you can specify the path info for the search service, version number, and specific type of search: NewsSearchService/V1/newsSearch |
params | (Optional) Query parameters specified by the REST service you want to address. |
headers | (Optional). HTTP headers containing connection, host, content type and other request details. |
payload | (Optional) The representation of the resource. This data can be character data or XML data. If it is character data, you should include the contentType attribute. |
queryString | (Optional) The string shown as it is formatted in the request. Contains parameters in the order they are specified. |
authType | (Optional) Value populated for inbound requests (receives). This value is equivalent to the value returned by getAuthType() method in javax.servlet.ServletRequest. The value can be one of the following: BASIC, FORM, CLIENT_CERT or DIGEST |
ssl | (Optional) Boolean. True if the request is sent as https. |
contextPath | (Optional) The application called in the request. |
requestURI | (Optional) The location of the service where the request is made. |
locales | (Optional). The ISO 639 Codes for country and languages. For example, <locale country="US" lang="en">en_US </locale> |
HTTP Methods:
HTTP defines eight methods indicating the action to be performed on the resource.
HEAD | Asks for the response identical to the one that would correspond to a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content. |
GET | Requests a representation of the specified resource |
POST | Submits data to be processed (for example, from an HTML form) to the identified resource. The data is included in the body of the request. This can result in the creation of a new resource or the updates of existing resources or both. |
PUT | Uploads a representation of the specified resource |
DELETE | Deletes the specific resource. |
TRACE | (Not supported for receives) Echoes back the received request so that a client can see what intermediate servers are adding or changing in the request. |
OPTIONS | Returns the HTTP methods the server supports. This can be used to check the functionality of a web server. |
CONNECT | (CURRENTLY NOT SUPPORTED) Converts the request connection to a transparent TCP/IP tunnel, usually to facilitate SSL-encrypted communication (HTTPS) through an unencrypted HTTP proxy. |
REST Response Message
The REST response message contains the parts shown below.
If you generate sample data for the response, be sure to change the statusCode attribute to a valid HTTP Status Code. The standard response for a successful HTTP requests is 200. The generated integer, "1", results in a fault being thrown.
<rest:RESTResponse
xmlns:rest="http://schemas.activebpel.org/REST/2007/12/01/aeREST.xsd"
statusCode="1">
<!--Optional:-->
<rest:headers>
<!--Optional:-->
<rest:header name="string" value="string"/>
</rest:headers>
<!--Optional:-->
<rest:payload contentType="string">
<!-- Payload information -->
</rest:payload>
</rest:RESTResponse>
If rest:payload is not qualified, it does not inherit the aeRest.xsd namespace as it did in Process Developer versions prior to 9.2. If you had relied on this inheritance, your XPath expressions may no longer work until you update your process.
REST Fault Message
A sample REST fault looks like the following:
<rest:RESTFault xmlns:rest="http://schemas.activebpel.org/REST/2007/12/01/aeREST.xsd" errorType="transport">
<rest:errorCode>400</rest:errorCode>
<rest:message>Bad Request</rest:message>
<rest:messageDetails>The request cannot be fulfilled due to bad syntax</rest:messageDetails>
</rest:RESTFault>
- •The errorType, defined in the above sample as transport, can be either transport or system.
- •The errorCode must be a HTTP Status Code, defined in the above sample as a 400 error.
BPEL REST Messages
The aeREST.xsd schema defines three message types:
- •RESTRequest. This is the message received by the server from a My Role endpoint and the message delivered by the server to a REST partner endpoint.
- •RESTResponse. This is the success response message returned to the server from a REST partner endpoint
- •RESTFault. This is the fault returned to the server from a REST partner endpoint with the HTTP error response or other system related faults.
For examples of each message type, see
Creating a REST-based Receive or Invoke.
Handling of Multipart HTTP Messages
Receives and Invokes support multipart HTTP messages.
There are two distinct classes of multipart messages, multipart/form-data and all others (for example, mixed, related, digest, parallel). Multipart/form-data represents data from an HTML form construct that can have parameters and files.
Receives
Multipart messages are parsed and populated in the RESTRequest message as a payload and attachments. The first textual message part is the payload all others are attachments.
For multipart/form-data, parameters are converted to RESTRequest message parameters. The first textual form data file becomes the payload, all others are message attachments. When there are no textual files there is no payload only attachments.
Invokes
Multipart messages are created implicitly when there are at least two of any combination of payload and attachments. The default Content-Type sent is multipart/mixed unless a multipart Content-Type header is defined in the RESTRequest message. An explicit Content-Type header of type multipart/form-data changes the behavior to emulate an HTML form submission. In this case all RESTRequest parameters in the payload are treated as HTML INPUT parameters, and attachments are treated as files.
Specifying Deployment Details for a REST-based Process
When you create a PDD file for a REST-based process, you must add the resource details and policies for the My Role and Partner Role endpoint references.
Partner Role
For a Partner role endpoint reference, select REST for the Invoke Handler. You can also add a HTTP Transport Policy Assertion to specify service timeout values.
There are no service bindings in the aeREST.wsdl so you can provide the endpoint reference by supplying the URL to the resource, such as:
<wsa:Address>http://search.yahooapis.com:80/NewsSearchService/V1/newsSearch</wsa:Address>
To use variable replacements for the specific service of the domain, you can use parameters in the address, such as:
<wsa:Address>http://nnnn.yahooapis.com:80/NewsSearchService/nn/newsSearch</wsa:Address>
The parameters can then be specified in the request message, as described in
Creating a REST-based Receive or Invoke.
My Role
For a My Role endpoint reference, ff the process is receiving REST requests, you must add a policy assertion for a REST-enabled service.
A REST service context policy example is as follows: