Posts Tagged ‘soa’
RESTEasy: Where did the hypermedia go to?
Some friends have asked what are the major differences between Restfulie and RESTEasy client frameworks.
Strong coupling and hypermedia awareless
As of today, Resteasy requires you to create an interface mapping every resource operation to a specific method, using @VerbName and @Path annotations to specify the desired target URI.
RESTEasy is ignoring the power of hypermedia content on the client side, thus being level 2 according to Leonard Richardson, and not matching Roy Fielding’s description.
RESTEasy is not Roy’s REST
But hypertext as the engine of hypermedia state is also about late binding of application alternatives that guide the client through whatever it is that we are trying to provide as a service.
Guess what? Java interfaces with @VerbName + @Path annotations means early binding, means an effort trying to describe which methods to use on which URI’s: tighter coupling, less space to evolve your server systems.
Going further:
It is fundamental to the goal of removing all coupling aside from the standardized data formats and the initial bookmark URI.
Restfulie provides a way to access only the initial bookmark URI, everything else is derived from navigating through your resources and its states.
Roy’s dissertation puts his believe quite clear in hypermedia being an important point of the web in chapter 5, his first paragraph: “Representational State Transfer (REST) architectural style for distributed hypermedia systems”.
RESTEasy got it right when it allows the user to access multiple URIs and the http protocol as the application protocol. But it still helps creating strongly coupled systems. Those who use JAXB (JAX-RS required) and fixed xml schemas do not allow server to evolve without prior notice to their clients. Ian Robinson has written about links in his blog and – another option – contract based systems in ThoughtWorks Anthology.
Back in 2007, there was a nice discussion on SOA allowing the users to create strongly coupled systems, where Mark Baker cleared it: SOA is constraintless, therefore one can create strongly and loosely coupled systems.
RESTEasy not supporting hypermedia content by default matches Roy’s definition of unrestful:
In other words, not RESTful at all. REST without the hypertext constraint is like pipe-and-filter without the pipes: completely useless because it no longer induces any interesting properties.
Although RESTEasy supports atom feeds, which is a good point, if the client wants a real hypemedia aware resource, he has to work on the deserialization process on his own.
RESTEasy does not provide the class generation mechanism that Restfulie (both Java and Ruby) provides so end users are able to transverse your resource’s tree and states without prior knowledge of every other URI.
According to Roy, one of the key benefits of the REST archicture style is its visibility through out the entire layered system:
REST is an architectural style that, when followed, allows components to carry out their functions in a way that maximizes the most important architectural properties of a multi-organizational, network-based information system. In particular, it maximizes the growth of identified information within that system, which increases the utility of the system as a whole.
By fixing all URI’s on the client side, along with not supporting hypermedia content by default, RESTEasy provides less information to layers contained between the server and the client: thus less visibility.
Server side
The same issues arrive when talking about the server side: RESTEasy does not provide any default interface for hypermedia content, but JAX-RS default support to JAXB: plain xml. It is up to (good) programmers to know how to make use of hypermedia systems in order to create a loosely coupled system.
Languages
Another key point on Restfulie’s approach is that it is Java-INdependent. Every month we see a larger number of integration software being developed in other languages: Restfulie can already help Java and Ruby developers.
quit pretending, use the web for real: restfulie
Resource representation
A simple resource representation in xml could be
<order> <product>basic rails course</product> <product>RESTful training</product> <price>500.00</price> </order>
It provides information on the order itself, as we are used to. But it lacks providing meta information on anything related to business process: from here, I am unable to go anywhere.
This resource is unable to lead its consumers through possible steps further on a business flow, i.e. creating a payment or cancelling it.
Looking at this resource, it is clear that it is just an usual “structural representation” of something that programmers would code in C: the data and it’s structure: but no possible actions.
Identifying resources
In order to access those resources, one needs to possess its address, its URI.
We use, for example, URIs to identify our courses at Caelum.
The advanced rails training can be accessed through the http://www.caelum.com.br/curso/rr-75-ruby-rails-avancado/ URI and also through http://www.caelum.com.br/curso/rr-75.
Note that there is no need to have an unique URI to resource or resource to URI mapping. In our case, the latter URI redirects to the first one through an http permanently moved response.
Web services
One can understand web services as services which use the web as its infrastructure. The basic step to create a web service is to use http requests to act.
Typical SOA applications will stop its evolution and its use of the web infrastructure here, not profiting from everything else that the web provides.
Resources accessed through the web
Once I have an URI in my hands, and a web service that provides me the resource representation through a web request (typically a GET request), one receives as output the requested resource representation.
Using different HTTP verbs and analyzing the request and result headers and codes, one makes and profits from further usage of the web infrastructures such as caching proxies and fault tolerance assurance due to idempotent methods.
Frameworks and applications, like the one from the spring blog, which provides the first level of web infrastructure usage would be called resource based web services (RBWS) if they were not lacking the use of the most common web aspect: hypermedia.
According to Roy Fieldings, “REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.”
Web service based CRUD
Web service based cruds are those ressemblingthe spring tutorial, which maps URIs to resources and allows the usage of different HTTP Verb, headers and return codes to sign actions and return values.
Although being a sign of better usage of the web in order to create web-based services, it is still missing the very best part of our every day life: hyperlinks and hypermedia content.
Doing CRUDs is an everyday task, and doing service based CRUD implementation is a nice and cute functionality that frameworks as rails, spring and vraptor allows us to do.
According to Leonard Richardson model, one can roughly categorize his usage of the web infrastructure based on which use one makes out of it. CRUD over the web is just the first step, and hypermedia support is the following one.
Hypermedia aware resources
Resources supporting hypermedia provide consumers the next steps to follow on an application business flow. It allows the consumer to change the application state as web requests are stateless.
The following code shows an example of xml+hypermedia representation of the same order seen earlier:
<order> <product>basic rails course</product> <product>RESTful training</product> <refresh>http://www.caelum.com.br/orders/1</refresh> <update>http://www.caelum.com.br/orders/1</update> <pay>http://www.caelum.com.br/orders/1/pay</pay> <destroy>http://www.caelum.com.br/orders/1</destroy> </order>
Note that this path is a simple yet powerful way of interacting with your clients. Although its a valid option, one can make use of the w3c atom format as nowadays there are hundreds of important tools atom-aware:
<order>
<product>basic rails course</product>
<product>RESTful training</product>
<atom:link rel="refresh"
href="http://www.caelum.com.br/orders/1"
xmlns:atom="http://www.w3.org/2005/Atom"/>
<atom:link rel="update"
href="http://www.caelum.com.br/orders/1"
xmlns:atom="..."/>
<atom:link rel="pay"
href="http://www.caelum.com.br/orders/1/pay"
xmlns:atom="..."/>
<atom:link rel="destroy"
href="http://www.caelum.com.br/orders/1
xmlns:atom="..."/>
</order>
Cutting a new gem
Both Jim and Savas have commented on the client simple javascript+html resource+hypermedia (restful?) client that we have created so one could easily test a restful application online.
So me and Caue Guerra at Caelum were ready to move to the next step: getting resource+hypermedia support to rails applications.
SOA applications, due to strange and dark forces, typically demand dozens of developers to built something complex and hard to maintain.
With this in mind, we have developed Restfulie, which is a rails based gem.
It works both on the server and client side making it easier to provide and consume such restful resources.
Requesting a resource
A resource based web services provider – another long name for a partial rest implementation based on roy’s dissertation – can access a resource through the api:
order = Order.from_web ‘http://www.caelum.com.br/orders/1’
Now, one can request its content
puts order.products
or even invoke those “methods”:
order.pay payment order.cancel payment = order.check_payment_info
All those three methods are remote invocations (never forget it!) that access the server executing POST, DELETE, PUT and GET operations, serializing and deserializing xml+atom content (or json, …).
Thats about it. You have consumed a resource representation and acted upon it in two lines of code, moving your resource to another state on your business flow.
Meanwhile, on the server side
Those who want to provider RBWS can easily do it using restfulie by implementing the method following_states as follow:
class Order
def following_states
states = [ { : orders, :action => :show } ]
states << : orders, :action => :destroy} if can_cancel?
states << : orders, :action => :pay, :id => id} if can_pay?
states
end
end
And in a 6 lines long method, one has implemented a full RBWS provider: all invocations to to_xml and to_json will serialize atom or rel based links to those state transition services.
Live examples
You can try the server side ordering application online and a sample client side application live at heroku.
In order to fully test those systems, follow the “Try it online” directions on the Restfulie website.
Concluding
This post gives a basic idea on resources, web based services and how one can really use the web to profit from its already existing infrastructure.
While some RBWS providers already use all this knowledge, most of the frameworks that we see today focus on “restful” meaning “accessing a resource through its URI and http verbs”. There is more to the web than just getting, posting and uris. There is a whole world hidden behind links so… let’s quit pretending and start using the web infrastructure for real.
Using the web infrastructure
Some recent posts here and at our company’s blog were dealing on how to use the web as an infrastructure for distributing an algorithm, but this post is related to how to supply a service or resource based system using some of the web infrastructure.
Last year, at Falando em Java 2009, Jim Webberr spoke about HATEOAS, Microformats and how hipermedia content could add to a servicing system.
Based on his upcoming book and some of the ideas presented on his blog, I have created a small project with the help of Adriano Almeida and Lucas Cavalcanti at Caelum to help others explore some of those topics in a easy way.
Two simple projects show off what hypermedia content can do to simple resource/service based applications.
The server application is responsible for a small and simple ordering system where one:
1. sends an order (post)
2. requests it’s status (get)
3. sends an update (post)
4. cancel it (delete)
5. pay it (post)
Actions 3-5 are made available through action 2: by getting the resource representation, one can parse it and find its available actions – leaving it to a human-programmed software to request the next step in its flow or, for those who see flow automation as a good thing, for an automatic generic client to decide whats the next step.
The client application is responsible for being a “generic client”. But a generic client can be something harmful too so its one designed for those users who want to test their servers and learn how those resources work.
In order to try out the applications, you can use the google app engine infrastructure and follow the steps below:
Entry Point
Every resource/service based application has a single or set of entry points. From the point of view that such integrated systems should be programmed by humans (and not entirely automated), the consumer application should be aware of the entry point and its http verb, therefore:
Access http://restful-client.appspot.com/ and try to post an order to:
a) entry point: http://restful-server.appspot.com/order
b) method: POST
c) name: content
d) content: any order content (it will not be validated)
This is a well-known entry point and both client and server application are aware and agreed on that. By following that mindset, one will have a set of those entry points that are aware for both sides.
Those who look for fully automated services or systems will probably create a single starting point containing a GET request which results in the set of former entry points.
Running the consumer application
PAY ATTENTION: you might need to run it twice when you first run it. google app engine has a slow startup time that
might run a timeout prior to succeeding.
After posting the order, you will receive a 201 response with your order location.
You can then view (GET) this order to see its representation. By parsing the representation, one can discover what you can do with your order:
– pay (request a payment POST)
– cancel (request an order DELETE)
– update (request an order UPDATE)
– view (request an order GET)
Anytime you can check your order status by getting it. After payment your status will change to PREPARING and after one minute it will be DONE. If you cancel your order, it will be CANCELED.
While the client application is mostly a javascript+html view of what is being consumed, it still contains some vraptor serving our requests. This way we were forced to visualize for the first time how can we generalize a little bit the idea so we create a somehow generic consumer library in Java.
At the same time, a ruby version of the server side library supporting services-aware-resources will be released here soon. The java version is also being built around vraptor already. The next step is to build a ruby library – due to its dynamic nature, one can create really nice resource representations on the client side of what we just received from the server.
Those interested in helping us are welcome to mail me.
Although its a simple server application, it is a good way to show how to use the web as an infrastructure in a little bit more than the (rest-non-ful) CRUD examples found on the web.
Guilhermesilveira's Blog 