Rest Service Invocation via BPEL

REST is an architectural style that communicates with URIs (Unified Resource Identifier) where data is transmitted like HTTP requests in real world scenarios. Traditional HTTP binding on WSDL only supports GET and POST operations. However, REST requires additional operations like PUT and DELETE. Those can be implemented using WSDL 1.1 Extensions for REST with Apache ODE. The sample used in this topic illustrates how you can invoke RESTful services with BPEL processes.

Deploying the sample

WSO2 BPS provides a sample that can be deployed and executed to understand the RESTful service support with BPEL. Follow the instructions below to deploy and trigger the process.

Deploying the BPEL sample

1. Log in to the BPS Management Console. 
2. Select Processes > Add under the Main menu.
3. Upload the UserRestProcess.zip file. Samples are located in the sample repository. 
4. In the Deployed Processes window, click the Process ID to access the Process Information window.
5. Under the WSDL Details widget, trigger the process using the TryIt link to create an instance of it.

Deploying the REST service

Deploy the UserProcess JAX-RS web application in any application server. You can use WSO2 Application Server to deploy the web application for testing purposes. Checkout the JAX-RS Rest process from the repository.

Using the service

The User REST Process takes input like user ID and username. With this information it creates a user in the service store using the PUT operation. The POST operation is used to update the username appended with '@wso2.com' and the GET operation provides the user object for the response, which is the output. Before sending the output, the DELETE operation is used to delete the user. The process does not do meaningful tasks but it was modeled to cover all four operations of the REST service. This is the BPEL model of the process.

The following table lists out the various operations and the respective details.

Accessing the REST service

All these REST operations are to be specified to get user input than hard coded values. BPEL accesses the external service using partner links via the WSDL files. When developing the BPEL process to call the REST service, it is required to create a separate WSDL file for that. That will use WSDL 1.1 extensions to add REST service calls.

For example, this is how you can get user input and pass it into the PUT REST operation via WSDL. For other REST operations you can use the same approach.

1. The following is the user schema that consists of the username and user ID.

   <wsdl:types>
     <xsd:schema attributeFormDefault="qualified" elementFormDefault="unqualified" targetNamespace="http://wso2.org/bps/ignorens">
      <xsd:element name="user">
       <xsd:complexType>
        <xsd:sequence>
         <xsd:element minOccurs="0" name="uid" nillable="true" type="xsd:string" />
         <xsd:element minOccurs="0" name="uname" nillable="true"
          type="xsd:string" />
        </xsd:sequence>
       </xsd:complexType>
      </xsd:element>
      <xsd:element name="userID">
       <xsd:complexType>
        <xsd:sequence>
         <xsd:element minOccurs="0" name="uid" nillable="true"
          type="xsd:string" />
        </xsd:sequence>
       </xsd:complexType>
      </xsd:element>
     </xsd:schema>
   </wsdl:types>

2. PUT messages can be defined as follows.

   <wsdl:message name="putUserNameRequest">
     <wsdl:part name="user" element="ignore:user" />
    </wsdl:message>
    <wsdl:message name="putUserNameResponse">
     <wsdl:part name="part" type="xsd:string" />
   </wsdl:message>

3. The port type for the PUT operations can be specified as follows.

   <wsdl:portType name="UserServicePutPT">
     <wsdl:operation name="putUserName">
      <wsdl:input message="tns:putUserNameRequest" />
      <wsdl:output message="tns:putUserNameResponse" />
     </wsdl:operation>
   </wsdl:portType>

4. WSDL binding for the PUT operation can be specified as follows. This example uses {} to get message request data (uid,uname) to pass it via the REST PUT URL.

   <wsdl:binding name="UserServicePutHTTP" type="tns:UserServicePutPT">
     <http:binding verb="PUT" />
     <wsdl:operation name="putUserName">
      <http:operation location="http://10.100.5.24:9764/UserService_1.0.0/services/user_service/userservice/users/name/{uid}/{uname}" />
      <wsdl:input>
       <http:urlReplacement />
      </wsdl:input>
      <wsdl:output>
       <mime:content part="part" type="text/xml" />
      </wsdl:output>
     </wsdl:operation>
   </wsdl:binding>

5. The service for the PUT operation can be written as follows.

   <wsdl:service name="UserServicePut">
     <wsdl:port binding="tns:UserServicePutHTTP" name="UserServicePutHTTP">
      <http:address location="http://10.100.5.24:9764/UserService_1.0.0/services/user_service/userservice/users/name/1" />
     </wsdl:port>
   </wsdl:service>

Sample input

<body>
   <p:UserRestProcessRequest xmlns:p="http://wso2.org/bps/sample">
      <!--Exactly 1 occurrence-->
      <id xmlns="http://wso2.org/bps/sample">10</id>
      <!--Exactly 1 occurrence-->
      <name xmlns="http://wso2.org/bps/sample">Waruna</name>
   </p:UserRestProcessRequest>
</body>

Sample output

<UserRestProcessResponse xmlns="http://wso2.org/bps/sample">
   <tns:put xmlns:tns="http://wso2.org/bps/sample">
      <result xmlns="">Waruna for id : 10 was added.</result>
   </tns:put>
   <tns:post xmlns:tns="http://wso2.org/bps/sample">
      <result xmlns=""> Name of user id: 10 was changed to Waruna@wso2.com</result>
   </tns:post>
   <tns:get xmlns:tns="http://wso2.org/bps/sample">
      <username xmlns="">Waruna@wso2.com</username>
   </tns:get>
   <tns:delete xmlns:tns="http://wso2.org/bps/sample">
      <result xmlns="">user id: 10 deleted.</result>
   </tns:delete>
</UserRestProcessResponse>