ModeShape's RESTful API was intended to be used by HTTP clients, so it's quite easy to write a simple client application to read and write repository content using the RESTful API. However, since our trusty web browser is indeed a simple HTTP client, we can use it to directly interact with the RESTful API. It might not be pretty, but it works beautifully.

The RESTful API is nothing more than a simple JAX-RS web application that is packaged as a WAR file, and the kit automatically deploys this WAR file for us. So let's use this to easily check the health and availability of the repositories. To do so, simply point your browser to http://localhost:8080/modeshape-rest/, and you should see a JSON response that is similar to the following:

{
    "sample": {
        "repository": {
            "name": "sample",
            "resources": {
                "workspaces": "/modeshape-rest/sample"
            },
            "metadata": {
                "option.retention.supported": "false",
                ...
            }
        }
    }
}

The response document lists the named repositories that are available. In this case, there is only one "sample" repository, and its nested document provides the name, resources and meatdata for the repository. The "resources" nested document contains the usable (relative) link that we can use to get more information about the repository.

To do this, we need to issue a GET to the resource at http://localhost:8080/modeshape-rest/sample, which we can do by pointing our browser to this URL. When we do this, the RESTful service will return a JSON response document describing the "sample" repository:

{
    "default": {
        "workspace": {
            "name": "default",
            "resources": {
                "query": "/modeshape-rest/sample/default/query",
                "items": "/modeshape-rest/sample/default/items"
            }
        }
    }
}

This document describes the repository and lists the named workspaces. In this case, there is a single "default" workspace, and two resources available for use:

• http://localhost:8080/modeshape-rest/sample/default/items exposes the repository's nodes via RESTful methods

• http://localhost:8080/modeshape-rest/sample/default/query allows RESTful clients to POST queries and receive responses containing the results

We can't issue a POST with our web browser (without some HTML/JavaScript content on the page), we can continue to navigate the content of the "default" workspace in the "sample" repository. For example, if we point our browser to http://localhost:8080/modeshape-rest/sample/default/items, we'll get a response that describes the root node of that workspace:

{
    "properties": {
        "jcr:primaryType": "mode:root",
        "jcr:uuid": "81513257505d64/"
    },
    "children": ["jcr:system"]
}

Here we see that the root node has two properties, "jcr:primaryType" and "jcr:uuid" (since the node is also 'mix:referenceable'), and one child node, "jcr:system". We can append the child name to our URL (e.g., http://localhost:8080/modeshape-rest/sample/default/items/jcr:system) to get the information about the "/jcr:system" node:

{
    "properties": {
        "jcr:primaryType": "mode:system"
    },
    "children": ["jcr:nodeTypes", "jcr:versionStorage", "mode:namespaces", "mode:locks"]
}

Here we see the "/jcr:system" node has only one property but has four children. Let's look at the "mode:namespaces" child node by pointing our browser to http://localhost:8080/modeshape-rest/sample/default/items/jcr:system/mode:namespaces to get its JSON representation:

{
    "properties": {
        "jcr:primaryType": "mode:namespaces"
    },
    "children": ["jcr", "nt", "mix", "sv", "mode", "xml", "xmlns", "xs", "xsi"]
}

Again, we see only one property, while there are 9 children: 1 for each registered namespace, where the node name is the namespace prefix. We can get the JSON representation of the "jcr" namespace by pointing our browser to http://localhost:8080/modeshape-rest/sample/default/items/jcr:system/mode:namespaces/jcr :

{
    "properties": {
        "jcr:primaryType": "mode:namespace",
        "mode:generated": "false",
        "mode:uri": "http:\/\/www.jcp.org\/jcr\/1.0"
    }
}

And here we see that the "/jcr:system/mode:namespaces/jcr" node has three properties and no children.