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.

9 comments:

nuwan said...

Hi Hiranya

We have done the same coffee-shop App[1] with Jaggery[2]. :)

[1] http://jaggeryjs.org/coffeeshop/
[2] http://jaggeryjs.org

Hiranya Jayathilaka said...

That's great. Ideally you should be able to run my UI tools against the REST API exposed by your Jaggery app.

Also one suggestion regarding the sample Jaggery app. Try to improve it so that it displays more complete wire level message traces. How HTTP headers like "Location" and "Accept" are used in applications is very important in REST+HATEOAS.

Unknown said...

Hi Hiranya.
I am very much new to wso2 and to rest services. I have created an API of rest service in my wso2 esb whose url is something like this:http://10.224.188.113:8280/students which does two operations insert on POST, Select on Get. But how can i access this rest service. I mean to say how i can invoke this service to access its operations without using curl ofcourse.

Hiranya Jayathilaka said...

I suppose you should use some kind of a REST client. You can either write a REST client using a HTTP library or use an existing one such as curl, jmeter and chrome rest client. Since you're only using GET and POST, you can probably write a web interface for this API too.

Unknown said...

Thanks for the reply.But agin i have a question. I have created api which is meant to get data in rest format. When i hit the url of my rest service then it gives me error saying
INFO {org.apache.synapse.mediators.builtin.LogMediator} - To: /GetCommonData/getUUID?Name=uvu, MessageID: urn:uuid:de71ac60-277d-4c7e-8638-cec63efd1af6,
Direction: request, searchValueProp = uvu {org.apache.synapse.mediators.builtin.LogMediator}
ERROR {org.apache.axis2.description.ClientUtils} - The system cannot infer the transport information from the /GetCommonData/getUUID?Name=uvu?Name=uvu URL.
{org.apache.axis2.description.ClientUtils}
ERROR {org.apache.synapse.core.axis2.Axis2Sender} - Unexpected error during sending message out {org.apache.synapse.core.axis2.Axis2Sender}
org.apache.axis2.AxisFault: The system cannot infer the transport information from the /GetCommonData/getUUID?Name=uvu?Name=uvu URL.

Hiranya Jayathilaka said...

Looks like a configuration error. I'd recommend you to reach out to WSO2 team through one of their mailing lists. Don't forget to share your API configuration too. Check http://wso2.com/mail for info on available mailing lists.

Unknown said...

Thanks for the reply hiranya.It was configuration related error.Now i want to implement security in my API's. You have mentioned about handler in your blog. I am wondering about where to put code in the api? And how will i invoke this secured api from a java client?

Hiranya Jayathilaka said...

You need to implement a security handler by implementing the Handler interface of Synapse (see https://synapse.apache.org/apidocs/org/apache/synapse/rest/Handler.html). You can deploy the code by compiling the handler into a jar file and deploying it into the ESB (by copying it into repository/components/lib I think).

To invoke a secured API you need to write a client application that knows how to authenticate it self according to the security protocol you have implemented in your handler. If it's the BasicAuth protocol, then the client should send his credentials in the Authorization header of the request (you need to do a bit of work here like base64 encoding the creds - Google it for more info).

Hiranya Jayathilaka said...

I'd also recommend you to look into WSO2 API Manager which uses the same REST mediation technology as WSO2 ESB and provides OAuth authentication for all APIs by default. You may contact the WSO2 mailing lists for any help.