For my last technical session of JavaOne 2011, I wanted to attend something "easy" with a short title because of the mental fatigue and crammed brain resulting from four days of blistering rate of technical information coming my way. With that in mind, I chose to walk across the hall from Hilton San Francisco's Golden Gate 6/7/8 to Golden Gate 3/4/5 for the presentation "REST and Hypermedia as the Engine of State with Standard Java APIs" (24609). Although I have worked with REST and JAX-RS/Jersey, the abstract of this presentation caught my eye. In addition, I believe that HATEOAS may be the least understood, most confusing, and most misused term (or unused portion) in all of REST-dom.
Stenflo briefly discussed the history of REST based on Fielding's famous dissertation. He mentioned that the "architectural style" of REST had been misused and hijacked by several to be a structural style. Stenflo then went on to discuss the basics of REST with definitions of terms like "resource." He also discussed the HTTP "verbs" and stated that "REST is about using the web the way it was intended." Stenflo discussed "self-descriptive messages" that "contain all information needed to complete a task" (this statelessness is what makes horizontal scaling easier).
Stenflo had multiple slides titled "HATEOAS: Hypermedia as the Engine of Application State." This concept allows for "discoverable resource interaction" and "allows resources to evolve over time." Stenflo explained that the consumer is provided with the correct link for a given resource.
Arthursson stated that if you're doing REST with Java, "you should probably be using JAX-RS." Arthursson introduced some of the key annotations that JAX-RS provides such as @Path, @GET, @POST, @PUT, and @DELETE. He feels (as do I) that the JAX-RS is one of the best JSRs in recent years. The Expert Group for JAX-RS 2.0 is about to publish a draft and the new version will focus on improvements requested from the community. These features include a common client API (that would be very nice) and "support for hypermedia" (JAX-RS currently does not support HATEOAS)
Until JAX-RS 2.0 implementations are available (and the spec is not even written yet!), we need a way to handle hypermedia in Java-based REST style applications. Arthursson introduced some approaches from RESTeasy Atom link, Jersey linking, and "purely annotation-based" approaches that are "more readable, "more versatile," and require DTOs to have "knowledge of hypermedia." His understanding is that the JSR Expert Group is leaning toward the annotation-based approach as well.
JAX-RS-HATEOAS is a small extension to JAX-RS to enable hypermedia in JAX-RS 1.x applications. Adding hypermedia to your existing application is easily done in four steps:
* Extend HateoasApplication (or JerseyHateoasApplication)
* Add a RequestContextFilter in your web.xml (enables the framework to get access to the full request URIs)
* Add @Linkable annotations to all methods that should be linkable.
* Use HateoasResponse instead for building responses with HATEOAS links.
The normal Response methods (ok, created, entity, etc.) will now return a HateoasResponseBuilder.
The HateoasResponseBuilder contains methods to easily add links to your responses:
** link(String linkId, Object... params) - adds a link to the referenced linkId
(as defined by an @Linkable annotation).
** selfLink(String linkId, Object... params) - adds a link to the referenced linkId with a 'self' rel
(rather than the default rel defined in the referenced @Linkable annotation
Arthursson covered these steps in his slides and then moved to an IDE (SpringSource Tool Suite) to show a live example. His examples demonstrated the ability to use
jax-rs-hateoas to provide hypermedia in responses (such as
HateoasResponse). The jax-rs-hateoas project seems pretty easy to use and it was stated that it's pretty small and is designed to allow developers to customize their hypermedia as necessary.
A good question was whether XML was supported in jax-rs-hateoas (only JSON was demonstrated). At this point, only JSON (the "cool stuff") is supported, but they acknowledged that XML needs to be supported.
This was an interesting presentation and looks like a promising solution for bridging the gap between today and JAX-RS 2.0 in terms of appropriately using HATEOAS in REST-based applications using JAX-RS. The project is still young, but could end up filling a niche in the Java/REST world. In the end, it's likely that JAX-RS 2.0 will make this obsolete, but that could be years from now.