By reza_rahman on Jan 13, 2016
The concepts of Hypermedia and HATEOAS (shorthand for the mouthful of "Hypermedia as the Engine of Application State") have made the rounds in the REST ecosystem for a little while now. If you Google around a bit you'll find no shortage of arcane academic-sounding text describing it's supposed universal virtues. For the rest of us a simple explanation is that it is an attempt to utilize web page style links in REST based web services. Using the hypermedia concept, you can send the client links for what they may be able to do further after receiving a REST response. A simple example is including links for canceling or getting details for an order in addition to a confirmed order object probably retrieved via a GET request. Although less common, links can also be embedded as data within the response. An example would be embedding a link to retrieve the delivery address in the order data body instead of embedding the actual address body or an address ID. Finding a reasonably down-to-earth, unpretentious explanation of Hypermedia was shockingly difficult. The best I could find is the humble documentation for the PayPal Payment REST API that makes real world use of Hypermedia.
In practical terms Hypermedia helps make clients more flexible by avoiding hard-coding REST URLs. It can also help in self-documenting REST APIs. If you look around on the web it is an open question whether these purported benefits are actually worth the additional implementation complexity. Hypermedia may be best applied in a situation when you are developing a public API where you do not know much about potential users of the API. The PayPal Payment REST API is a good example of such a case.
The good news is that if you have a good use case for Hypermedia Java EE 7 adds support for it via JAX-RS 2. Sam Sepassi recently did an excellent write-up detailing the newly added API. It is far and away the best write-up that exists on the topic. He includes a brief explanation of Hypermedia including example code using JAX-RS 2. He also included some details on experimental work that is being done in the Jersey JAX-RS RI to include support for declarative Hypermedia (the Hypermedia APIs added in JAX-RS 2 are basically programmatic).
Enjoy and feel free to share with anyone that you might think would find this useful.