Discovery and exploration of RESTful resources using Adjoovo Spaces

Adjoovo is pleased to announce the first community release of Adjoovo Spaces, now available as a free download. Trying to explain what Adjoovo Spaces is all about in a nutshell would not do it justice since it is many things to many people. For now, I'll just present an example usage scenario to show some of the product's capabilities, but if you must know more before this - well, think of Spaces as a mashup of:

• a general purpose registry / repository,
• a discovery tool for services / resources, classes, processes ...
• a dependency analysis and impact tool,
• a reverse engineering tool supporting preferred views for many different development artifacts,
• a rich GUI supporting web 2.0 annotative features, including a built-in wiki.

I could go on (and on) but I'll stop there for now.

This post concentrates on some of the RESTful aspects and useful features for developers working with and/or building their own RESTful applications and resources. Spaces takes the concept of a traditional registry / repository, but replaces UDDI for REST (specifically JAX-RS and Jersey) to publicly expose and open up its capabilities to any number of potential uses.

You can import a number of different development artifacts into Spaces (e.g. JARs, WSDLs, XSDs, Maven POMs and WADL files) and as part of the filter extraction process, it will load in all of the important entities and relationships between them as derived from the artifacts you provide it.

Let's take an example by looking at Spaces' own REST API from within the Spaces web UI. We can import the application.wadl file from the Jersey base URL directly into Spaces via its UI or even via curl.

Add Artifact Dialogue (Click to enlarge)

The extraction process is quick (and painless!) and new entities are created in the 'adjoovo' space. We are presented with some summary information, and updated tag clouds and most used entities list, which along with an autocomplete quick search and entity list tab, provides us multiple ways to learn about and navigate between what is important to us in our API; and all this without us telling Spaces anything at all about the WADL file we imported other than its location. The original WADL file is stored 'unmodified' in the Spaces repository, and all extracted entities exist in its registry database.

Space Summary view (Click to enlarge)

If we navigate to an extracted entity, such as a WADL resource, the tab view identifies the appropriate view for this entity and, in this case, presents us with a REST resource tree which allows us to browse the API and view the documentation, representations, parameters and media types that have been defined on each resource in the original WADL file.

RESTful Resource view (Click to enlarge)

We can add annotations to add some notes to this entity using one of the different property editors such as the built-in wiki or keyword/tags editor. We can even enrich data by adding or overriding manual dependencies all within the property editor. These annotations are non-destructive and thus do not affect the artifact stored in the repository. They are immediately exposed through the system search and any tag clouds and other view widgets are updated.

Property Editor view (Click to enlarge)

Furthermore, if we navigate to an entity which has dependencies e.g. the base resource at /spaces/rest, we can view a dependency graph which allows us to visually "wade into" the resources and methods available in the RESTful API. The resources and methods are clearly labelled and colour-coded and we can instantly see if a 'node' is expandable and thus has further resources and/or methods.

Graphical Dependency view (Click to enlarge)

Warning: the above tool is addictive and makes learning a new API a lot of fun! The application of this tool is not limited to any particular filter types and can be used to analyse message dependencies between WSDLs and XML schemas, artifact dependencies in a Maven POM file, and even a nested ZIP archive containing nested JARs and other artifacts. The latter is quite common if you work with JBI!

Also of note for working with RESTful resources is the ability to enable one-click loading of WADL artifacts (and others) over HTTP from popular repositories such as zembly.com, directly via wiki text markup. For an example, take a look at the Third-party artifacts page which allows you to load the Google Search REST API directly from zembly.com.

Wiki Markup Upload (Click to enlarge)

Adjoovo Spaces is a new project and as such we look to the community for feedback on our latest community download. There are many things planned in future releases and we value any feedback and stories on how Spaces might help you and how it could be made more useful for your development projects.

My journey with REST

The transition from Web Services...

I have been working closely with web services and the Java WS-* set of technologies since their inception. It has often occurred to me that the contractual interface required to build simple services, like a simple echo service, was far too complex to build, write and unit test when working with web services and a simpler dialect was needed. Historically, special tooling was almost always needed to assist with the creation of the required WSDL, XSD and SOAP messages to test with. Later EJBs tried to make life easier for building web services as POJOs, however, in practice still required WSDL-first development in many cases since the auto-generation of WSDLs and XSDs from EJB method signatures could often not guarantee WS-I compliance. Java now provides many standards and different implementations for how to host web services - e.g. EJB, servlets, JBI, SCA, {your app server}, {your ESB}, BPEL engines, OpenESB, Axis, CXF, Mule and the list goes on.

... to RESTful services

Then thanks to Roy Fielding's dissertation, along came REST, and although it was always there to begin with, the complexity of the WS-* specification and need to actually build web services for the web (e.g. Twitter API) fuelled the need and adoption for 'looser' RESTful services. Google quietly dropped their SOAP search API back in 2006 in favour of a RESTful approach and have not looked back since.

WS-* has its uses and let's not forget that - I wouldn't expose a complex message format interface to a corporate HRM system using REST. This trend of reducing complexity and consideration of REST has led to what I hope will be a generally-adopted standard for writing RESTful services in Java, using JAX-RS.

Why JAX-RS?

JAX-RS (JSR 311) is the Java API for RESTful Web Services. I don't quite know why it falls under the JAX (Java API for XML) branch, since it doesn't mandate XML but I think I know why Java developers needed something like JAX-RS. To build REST-based applications in the past, you had to do some low-level things with servlets which could get quite ugly (errr...how do I assign regular expressions as servlet mappings in web.xml?) and would no doubt end up reinventing the wheel on each new project. Looking at some of the innovation happening in the industry with clean approaches to building RESTful applications from the ground-up, such as Ruby on Rails, and the plethora of proprietary Java web frameworks out there, it was apparent that Java developers needed some standards to meet the demand for the growing trend of RESTful applications. Since its inception in 2007, the JAX-RS expert group has done a great job in my opinion by giving Java developers a simple and flexible approach for developing RESTful applications. From my experience so far, Sun's "reference implementation"(1) in Jersey is feature-rich, robust, makes testing very easy and has a great community following with hooks to many other popular open source projects, all making for a very active and responsive community which has caught my attention as of late.

(1) I don't like calling Jersey the reference implementation here due to the stigma associated with that.


SOA vs ROA

At JavaOne 2009, I attended a number of talks on REST and JAX-RS. All were very good and each of the speakers tried to promote REST but distance themselves from the ongoing REST vs WS-* debate. I particularly enjoyed Paul Sandoz and Mark Hadley's introduction to JAX-RS and Jersey. Doug Tidwell did a great job of evangelizing about REST and used Adam Koford's HTTP error codes images to very amusing effect.

The general consensus with REST vs WS-*, as with most technology debates, seems to be that each have their merits and it really depends on what you're doing. I would go as far to say that there isn't really a comparison to be made here that is any different from comparing something like JMS to WS-*. They are just both ways of delivering SOA, with relative merits and weaknesses. Given that REST services normally piggy-back off HTTP and can be accessed via URLs, they are particularly suited to web resources rather than services and can take advantage of the well-defined HTTP specification to handle things such as hyperlinks, error codes, redirects to newly-created resources etc.... The hype in the industry around REST and its suitability to HTTP resources for the web has led to the introduction of more catchy acronyms such as - Resource Oriented Architectures (ROA), Web Oriented Architectures (WOA).

RESTful solutions and the JAX-RS implementation is appealing to Java developers who just like simple solutions to simple problems. I'm a big fan of reducing complexity where possible and very much like what I see so far. And so my journey begins with REST...

In my next post, I'll start to look at JAX-RS and Jersey in more detail.