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.