Tuesday, April 10, 2012

WSO2 ESB Tips & Tricks 09: Introduction to REST APIs

REST API support is one of the coolest features we have added to WSO2 ESB in the recent past. It was first released in last December along with WSO2 ESB 4.0.3, and we have already seen a fairly large number of users embracing the new feature. I blogged about this addition in last January, in an introductory post about the WSO2 ESB 4.0.3 release.
Today I intend to briefly describe how we can start using this feature in simple integration scenarios. Assume you have an account management service implemented on a SOAP stack such as Apache Axis2. Your service may support basic crud operations such as create-account, read-account, update-account and delete-account. The create-account operation would take several inputs and create the account in a backend business system. Usually each account would be associated with some sort of a unique ID which can be passed in as a parameter to read, update and delete operations. Now assume that you want to expose this SOAP service through a RESTful API. Many architects and developers are currently looking for ways to easily expose existing SOAP services over REST, so that the services can be easily consumed by mobile clients and other web clients. With the REST API support in WSO2 ESB, such a REST to SOAP conversion is like an evening stroll in the park. Here’s the API configuration for the create-account operation.
<api name="AccountManager" context="/accounts">
<resource methods="PUT">
<inSequence>
<payloadFactory>
<!-- Create custom SOAP payload -->
</payloadFactory>
<send>
<endpoint>
<address uri="http://backend.service/url" format="soap11"/>
</endpoint>
</send>
</inSequence>
<outSequence>
<property name="HTTP_SC" value="201" scope="axis2"/>
<send/>
</outSequence>
</resource>
</api>
The above API can be invoked by sending a HTTP PUT request to the URL http://host:port/accounts. The payload of the request should have all the parameters required to create the account encoded as a XML document, a JSON string or any other suitable format. The ESB would do the REST to SOAP conversion and invoke the backend SOAP service. The response from the backend service will be sent back as a RESTful response with the HTTP status code 201. If possible it is also possible to add a custom Location header to the outgoing response. In a proper RESTful design, the Location header should be URL which points back to the read-account operation of the REST API.
Similarly more resource elements can be added to the above API to expose read, update and delete operations of the backend service. The full configuration would look something like this.
<api name="AccountManager" context="/accounts">
<resource methods="PUT">
...
</resource>
<resource methods="GET" uri-template="/account/{accountId}">
...
</resource>
<resource methods="POST" uri-template="/account/{accountId}">
...
</resource>
<resource methods="DELETE" uri-template="/account/{accountId}">
...
</resource>
</api>
Note how we map each HTTP verb to a unique operation in the backend service. Also note the usage of URI templates to specify request URL patterns to accept. WSO2 ESB has full support for level 1 and level 2 URI templates as described in the URI templates draft specification. Alternatively you can also use servlet style URL mappings to configure your API resources.
<api name="AccountManager" context="/accounts">
<resource methods="GET" url-mapping="/account/*">
...
</resource>
</api>
I believe the above example gives a basic idea on how the REST API support in WSO2 ESB can be used to implement real-life integration solutions. While this feature can have many potential use cases, one of its most powerful capabilities is to expose existing SOAP services and legacy systems over REST. Thanks to the REST API support in WSO2 ESB, implementing a RESTful overlay for an existing application is easier than never before.

4 comments:

Karaline Smith said...

Wonderful post you describe how can start using feature in simple integration scenarios.I implemented on a SOAP stack such as Apache Axis2.It perform function such as create-account,read-account, update-account and delete-account.Its work great and i am tottly satisfied.
error
134

thanks.

Karaline Smith said...

Wonderful post you describe how can start using feature in simple integration scenarios.I implemented on a SOAP stack such as Apache Axis2.It perform function such as create-account,read-account, update-account and delete-account.Its work great and i am tottly satisfied.
<a
href="http://best-registry-

Michael Manning said...

Could you possibly show an example of how the WSO2 API would communicate with a back end REST service instead of a SOAP service?

Hiranya Jayathilaka said...

You don't have to do anything special. Simply taking out the format="soap11" attribute off the endpoint definition should suffice in most cases.