Showing posts with label rest. Show all posts
Showing posts with label rest. Show all posts

Tuesday, September 11, 2012

How to GET a Cup of Coffee the WSO2 Way: An Article

Since we implemented REST API support for WSO2 ESB (and Apache Synapse), we have received many requests for new samples, articles and tutorials explaining this powerful feature. I started working on an end-to-end sample for API support somewhere around March but didn't have enough cycles to write it up. Finally, after a several months delay, I was able to submit the finalized sample and the article to WSO2 Oxygen Tank last month. Now it has been published and available for reading on-line at http://wso2.org/library/articles/2012/09/get-cup-coffee-wso2-way
This articles starts with a quick overview on the REST support provided by WSO2 platform. It describes the API mediation capability of the ESB in detail providing several examples. Then the article explains how a complete order management system can be constructed using the REST support available in WSO2 ESB. This sample application has been inspired by the popular article on RESTful application development titled "How to GET a Cup of Coffee" by Jim Webber. Webber's article describes a hypothetical application used in a Starbucks coffee shop which supports placing orders, making payments, and processing orders. The sample described in my article implements all the major interfaces and message flows outlined by Webber. I have also made all the source code and configurations available so that anybody can do the same on their own machines using WSO2 middleware. To make it even more interesting I also implemented a couple of user interfaces for Webber's Starbucks application. These UI tools are also described in my article and they can help you better understand how the applications communicate with each other using RESTful API calls and how their application states change according to typical HATEOAS principles.
Towards the latter part of the article I discuss some of the advanced features of RESTful application development and how such features can be implemented on top of WSO2 middleware. This includes some very important topics such as security, caching and content negotiation.
I hope you will find this article interesting and useful. As always feel free to send any feedback either directly to me or to dev@wso2.org.

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.

Wednesday, January 4, 2012

WSO2 ESB 4.0.3 is Out with REST API Support

WSO2 ESB 4.0.3 is now available for download. This contains several bug fixes over WSO2 ESB 4.0.0 and 4.0.2 releases. In addition to that this release comes with the highly anticipated REST API management support. This is a very powerful feature which I believe will be a game changer. I'm planning to do a series of blog posts and articles in the near future describing various use cases and capabilities of this brand new feature. At WSO2 we have already done some public webinars, workshops and development work for actual customers using the REST API support in the new ESB release and the feedback we have received so far has been phenomenal.
REST support is nothing new for WSO2 ESB. Even though we are primarily based on Apache Axis2, which is a SOAP engine, we have always had support for exposing RESTful interfaces and mediating RESTful invocations. However REST support in WSO2 stack was always a bit of a black sheep in the family. More often than not REST was perceived as a second class citizen in the WSO2 stack. But the new REST API support we have implemented changes all that. Now REST fans can easily define REST APIs and associated resources on the ESB and combine them with the powerful mediation features provided by the underlying messaging framework. Instead of worrying about mapping REST concepts to SOAP (which was the old way of handling REST calls with proxy services), developers can now configure REST endpoints in the ESB by directly specifying HTTP verbs, URL patterns (servlet styled), URI templates, HTTP media types and other related headers. Most REST fans will find themselves at home when working with the new API support in WSO2 ESB.
That's only a beginning. We are also looking into combining some of our best products together (including ESB of course) to come up with a comprehensive API management solution. This will be a complete platform where developers will be able to develop and expose REST APIs and users can subscribe and consume them.
As shown in the above diagram, core API management features such as API key management, user management, security and SLA monitoring are all provided by the solution itself. We are also looking at how to leverage our multi-tenant support to make this solution work seamlessly in the cloud.
If you are interested in learning more about the new REST API support in WSO2 stack and our future plans in this area, we are conducting a series of workshops on this very topic in US later this month. I'm sure you will find these sessions both interesting and eye opening. Also stay tuned for my own blog posts and articles on the subject which will give a more in-depth technical insight on the matter.