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.