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
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:
|
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> .
|
|
The HTTP method to execute. See the HTTP Methods table below.
|
|
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
|
|
(Optional) Query parameters specified by the REST service you want to address.
|
|
(Optional). HTTP headers containing connection, host, content type and other request details.
|
|
(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.
|
|
(Optional) The string shown as it is formatted in the request. Contains parameters in the order they are specified.
|
|
(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
|
|
(Optional) Boolean. True if the request is sent as https.
|
|
(Optional) The application called in the request.
|
|
(Optional) The location of the service where the request is made.
|
|
(Optional). The ISO 639 Codes for country and languages. For example,
<locale country="US" lang="en">en_US </locale>
|
HTTP defines eight methods indicating the action to be performed on the resource.
|
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.
|
|
Requests a representation of the specified resource
|
|
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.
|
|
Uploads a representation of the specified resource
|
|
Deletes the specific resource.
|
|
(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.
|
|
Returns the HTTP methods the server supports. This can be used to check the functionality of a web server.
|
|
(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.
|
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.
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.
