Thursday, November 14, 2013

Learner Series: Build/Consume HTTP REST Services in SOA 11g (with example)

Today REST (Representational State Transfer) has become a norm for building services on the web. REST brings along its own merits & demerits - choice of REST vs SOAP/WSDL, when and where is an architectural decision. So, how does Oracle SOA BPEL support HTTP based RESTful web services.

For all HTTP based interactions, Oracle SOA 11g provides an out-of-box HTTP Binding adapter.

This post will illustrate the following;

a) Expose a SOA 11g BPEL process as a HTTP REST service
b) Consume/Invoke a HTTP REST service from a SOA 11g BPEL process [We will consume service that we will build as part of (a)]

As part of this exercise, we will build a REST service that will take customer name & id as input and greets the customer.

Before dunking into building the SOA composites, let's quickly take a look at the XML schema that will form the REST service contract.
Exposing SOA 11g BPEL Process as HTTP REST service:

Step 1: Create a SOA Project with empty composite and name it "HttpGetRestService"

Step 2: Drag and Drop a HTTP Binding adapter on the "Exposed Services" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name
 Step 5: Choose "Define from operation and schema (specified later)" option
Step 6: Choose the following options and click Next

Type: Service [You will choose "Reference" if you need to consume a HTTP REST service]
Operation Type: Request-Response [For 2-way communication. Choose One-way if the service doesn't return a response]
Operation Name: Defaults to Request-Response [You can change it as you please]
Verb: GET [This specifies the HTTP method. You have 2 options GET/POST]
Payload Type: url-encoded [For HTTP GET method, SOA 11g support only payload type of url-encoded (name-value pairs). For HTTP POST, you get 2 options url-encoded and XML]


Step 7: In the Messages dialog, select the GreetCustomer.xsd, <CustomerInput> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.

Step 8: In the summary page, click "Finish" to complete service

Now, drag and drop a BPEL Process on the "Components" section.

Name the process as "GreetCustomerProcess" and choose to define service later.
You can now proceed to build the BPEL process as you please. As part of this sample, I have concatenated the customer name input with "Welcome" prefix so that the service returns the greeting as response.

Finally, deploy this project to your SOA server.

On deployment you can notice that the service is exposed both as a WSDL based webservice and HTTP based REST service. This will enable clients to interface through either standards.


You can test this service either via Enterprise Manager (EM) console - test mode or via normal browser.

For testing your SOA 11g based HTTP service refer to my blog entry here

Consuming a HTTP REST service in SOA 11g BPEL process:

Step 1: Create a SOA Project with empty composite and name it "InvokeHttpGetService"

Step 2: Drag and Drop a HTTP Binding adapter on to the "External References" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name
 Step 5: Choose "Define from operation and schema (specified later)" option
Step 6: Choose the following options and click Next

Type: Reference [Since we are consuming a HTTP REST service]
Operation Type: Request-Response [Default selection for references]
Operation Name: Request-Response [Default]
Verb: GET [This specifies the HTTP method. You have 2 options GET/POST]
Payload Type: url-encoded [Default]
Endpoint: Provide the HTTP URL for the REST service to be invoked. In this case, you can obtain the HTTP URL from enterprise manager console.

Step 7: In the Messages dialog, select the GreetCustomer.xsd, <CustomerInput> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.


Step 8: In the summary screen, click Finish to complete the service adapter

Now, drag and drop a BPEL Process on to the Components section of your SOA composite. Provide a name to the process, accept other defaults and click OK

Wire the BPEL process with the HTTP Binding adapter in the SOA composite.

Inside the BPEL process, just map the input payload element to the <Name> element of the greeting rest service and deploy to SOA server.

You can now test and check both SOA services in action. One will expose itself as a REST service and the other will invoke it.

Source code can be downloaded here

Let me know your thoughts in comments section.

13 comments:

  1. My RESTful service is returning a HTTP 500 status code and SOA is trying to process the HTML error page. How would you address this use case?

    ReplyDelete
    Replies
    1. Hi,

      You should handle the fault in your BPEL process. Irrespective of what adapter you use in your SOA composite, you must handle potential faults using fault policies. Take a look at the SOA dev guide for more details on handling faults.

      Delete
  2. HI Sathya,
    I am getting this error while i try to invoke my rest api.
    REST API.java.lang.ClassCastException: oracle.j2ee.ws.mdds.ComplexPrototypeImpl

    Do you how we can resolve this.

    ReplyDelete
    Replies
    1. Safeeq, Very little information for any suggestion/help. Which REST API are you trying to invoke? Can you invoke it successfully from a REST client/browser?

      Delete
    2. Hello Safeeq,
      Did you get to fix the above issue. Will you please let me know on the fix. I'm encountering similar issue in calling a rest service form Bpel.

      Delete
  3. hi...
    up post is really great and easy to understood...
    i have a question..I want to invoke my Asyncronous BPEL Service as a RESTful serivce and when i do that by adding a HTTP binding adapter it makes me confusing,,as if we select the Request-Response how the Asynchronous BPEL gonna respond to the HTTP Binding Adapter....

    thanks in advance...

    ReplyDelete
    Replies
    1. You have two options - oneway and request-response while creating a HTTP binding adapter. You have to choose the appropriate option based on the requirement.

      Delete
  4. How can i expose the same service only on HTTPS and not HTTP, as when we deploy the service on weblogic it get exposed on both HTTP and HTTPS

    ReplyDelete
  5. Nice Post with clear steps

    ReplyDelete
  6. Hi,

    How do pass a queryString to the RESTFul service, Assume it doesn't take any XML input.

    Can we consume any RESTFul Service using HTTP Adapter? If yes, how do pass queryString values from a BPEL process?

    ReplyDelete
    Replies
    1. If you are using SOA 12c, then you can use the exclusive REST adapter for non-XML payloads like JSON or URL Encoded. This post was written for 11g, where we had to make-do with a HTTP adapter to invoke REST services with the limitation of XML payloads only.

      Delete
  7. Hello Satya, I am facing difficulty consuming a REST/JSON service in BPEL. Do you have an sample to code or procedure..Please help me. We are using 11117 version.

    ReplyDelete
    Replies
    1. Hi Nisar,
      There is no direct way to do this in 11g, since we have to make-do with the HTTP Adapter. With SOA 12c, we have the exclusive REST adapter that supports REST services with JSON/XML payloads.

      Delete