Restful Java with Jax-RS (Animal Guide)

No one really enjoys reading specs, particularly not JSRs (Java Specification Requests, for those of you who are lucky enough not to have encountered these fun-filled documents). For those of you doing Java web development and looking for a good way to build RESTful applications, this might have been a sore spot when trying to understand JAX-RS -- the Java specification that outlines an API for building REST apps using annotations.

While both Jersey and RESTeasy, two popular implementations of JAX-RS, do provide fairly helpful user guides, the specification provides a wide-ranging set of capabilities and neither sufficiently conveyed the breadth of these, in my opinion. But now there is a new resource in the form of Bill Burke's RESTful Java with JAX-RS. Bill is the creator of JBoss' RESTeasy framework so he knows the specification well and it shows in this book.

The book explores building a RESTful web app from the ground up and includes a full workbook in the second section with complete examples. The examples are included with the download of RESTeasy, which was not immediately obvious on my first read through. Each chapter of the workbook matches a chapter from earlier in the book giving the reader the opportunity to try out the ideas they've just read about. This feels like a good format for a book like this -- a motivated reader can charge through the content of the book to get a cohesive view of the API, while not getting too bogged down in the details of setting up each example.

Some of the most interesting material that's harder to get from the users guides and online tutorials is covered in the material on content negotiation in chapter eight and content marshalling in chapter six. The content marshalling chapter not only explains the built in marshalling capabilities and the use of JAXB but also details how to add in custom handlers. While I don't know how much this will get used in practice given the ubiquity of JSON and XML, I suspect for those few who really need to supply their own data formats or who want to replace the built-in handlers will be more than happy to see it covered here.

I have to say that I felt like some items were not covered which would have been useful. For instance, I would love to see some examples of integrating with existing web apps and frameworks. It's not immediately clear what the best route is here and searching online turns up few, if any, best practices or war stories. Similarly it seems that a section on testing REST-based applications would have been called for, even if it isn't strictly part of the specification. I guess the book tries to stick to outlining JAX-RS within the context of the spec, but this feels to me a bit too limiting in scope. In general, some guidelines on best practices, common integration and usage scenarios and other "real world" content would have been a welcome addition.

Despite these minor complaints, this book is clearly a must have if you're venturing down the path of RESTful Java development. The existing documentation is far too-limited and this book is an easy and even enjoyable read.