Red Hat Training

A Red Hat training course is available for Red Hat JBoss Data Virtualization

Chapter 5. The REST Service

The hierarchical database's RESTful API was intended to be used by HTTP clients, so it is convenient 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 that comes in 2 flavors:
  • modeshape-web-jcr-rest-war - is a war file artifact available via Maven that can be deployed into any servlet container. To access it, include the following dependency in your project's POM: 
    <dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-web-jcr-rest-war</artifactId>
  <version>${modeshape.version}</version>
  <type>war</type>
</dependency>
  • The JBoss EAP kit - once installed into JBoss EAP, it provides the RESTful API out-of-the-box, via a web application.
Both web applications use Basic HTTP Authentication and require a role named connect to be present in the authenticated user's set of roles.
The hierarchical database provides two different versions of the RESTful API:
  1. REST Service 2.x - the version which was included in previous versions and which has been deprecated. However, for backwards compatibility it is still accessible using the v1 URL prefix: http://<host>:<port>/<context>/v1/
  2. REST Service 3.x - a newer version which is an extension of the old one, plus a number of additional improvements.

5.1. REST Service 2.x

Represents the version of the RESTful API distributed with previous versions. It has been deprecated in this release, but is still available using the v1 URL prefix. It provides the following methods:
Retrieve a list of available repositories
URL : http://<host>:<port>/<context>/v1/
HTTP Method : GET
Produces : application/json; text/html; text/plain;
Default Output : text/plain
Response Code (if successful): OK
Response Format : 
{
   "repo":
   {
       "repository":
       {
           "name": "repo",
           "resources":
           {
               "workspaces": "/resources/v1/repo"
           },
           "metadata":
           {
               "option.retention.supported": "false",
               "query.xpath.doc.order": "false",
               ...
         }
       }
   }
}
Retrieve a list of workspaces for a repository
URL : http://<host>:<port>/<context>/v1/<repository_name>
HTTP Method : GET
Produces : application/json; text/html; text/plain;
Default Output : text/plain
Response Code (if successful): OK
Response Format : 
{
       "default":
       {
           "workspace":
           {
               "name": "default",
               "resources":
               {
                   "query": "/resources/v1/repo/default/query",
                   "items": "/resources/v1/repo/default/items"
               }
           }
       }
    }
Retrieve a node or a property
Retrieves an item at a given path.
URL : http://<host>:<port>/<context>/v1/<repository_name>/<workspace_name>/items/<item_path>
HTTP Method : GET
Produces : application/json; text/html; text/plain;
Default Output : text/plain
Response Code (if successful): OK
Optional Query Parameters :
  • depth - a numeric value indicating how many level of children should be retrieved under the node located at path. A negative value indicates all children
  • mode:depth - same as the above
Response Format : 
{
       "properties":
       {
           "jcr:primaryType": "mode:system"
       },
       "children":
       [
           "jcr:nodeTypes",
           "jcr:versionStorage",
           "mode:namespaces",
           "mode:locks"
       ]
    }
Create a node
Creates a node at the given path, using the body of request as JSON content
URL : http://<host>:<port>/<context>/v1/<repository_name>/<workspace_name>/items/<node_path>
HTTP Method : POST
Produces : application/json; text/html; text/plain;
Default Output : text/plain
Request Content-Type : accepts any, but for this to work it has to be a valid JSON object
Response Code (if successful): CREATED
Optional Query Parameters :
  • mode:includeNode - indicates if the entire node should be returned in the response or only the path to the new node.
Request Format : 
{ "properties":{
    "jcr:primaryType":"nt:unstructured",
    "testProperty":"testValue",
    "multiValuedProperty":["value1", "value2"]
    },
    "children":{
        "childNode":{
            "properties":{
                "nestedProperty":"nestedValue"
            }
        }
    }
}
Response Format : 
{"properties":{
    "jcr:primaryType":"nt:unstructured",
    "multiValuedProperty":["value1", "value2"],
    "testProperty":"testValue"
}, "children":{
    "childNode":{
        "properties":{
            "jcr:primaryType":"nt:unstructured",
            "nestedProperty":"nestedValue"
        }
    }
}}
Update a node or a property
Updates a node or a property at the given path, using the body of request as JSON content
URL : http://<host>:<port>/<context>/v1/<repository_name>/<workspace_name>/items/<item_path>
HTTP Method : PUT
Produces : application/json; text/html; text/plain;
Default Output : text/plain
Request Content-Type : accepts any, but for this to work it has to be a valid JSON object
Response Code (if successful): OK
Request Format :
Node: same as the one used when creating
Property: 
{"testProperty":"some_new_value"}
Response Format :
Node: same as one used when creating
Property: 
{"testProperty":"some_new_value"}
Delete a node or a property
Deletes the node or the property at the given path.
URL : http://<host>:<port>/<context>/v1/<repository_name>/<workspace_name>/items/<item_path>
HTTP Method : DELETE
Produces : none
Response Code (if successful): OK
Execute a JCR query
Executes a JCR query in either: XPath, SQL or SQL2 format, returning a JSON object in response.
URL : http://<host>:<port>/<context>/v1/<repository_name>/<workspace_name>/query
HTTP Method : POST
Produces : application/json; text/html; text/plain;
Request Content-Type : application/jcr+sql; application/jcr+xpath; application/jcr+sql2; application/jcr+search
Default Output : text/plain
Response Code (if successful): OK
Optional Query Parameters :
  • offset - the index in the result set where to start the retrieval of data
  • limit - the maximum number of rows to return
Response Format : 
{
       "types":
       {
           "nt:base.jcr:primaryType": "STRING",
           "nt:base.jcr:mixinTypes": "STRING",
           "nt:base.jcr:path": "STRING",
           "nt:base.jcr:name": "STRING",
           "nt:base.jcr:score": "DOUBLE",
           "nt:base.mode:localName": "STRING",
           "nt:base.mode:depth": "LONG"
       },
       "rows":
       [
           {
               "nt:base.jcr:primaryType": "mode:root",
               "nt:base.jcr:path": "/",
               "nt:base.jcr:name": "",
               "nt:base.jcr:score": "0.3535533845424652",
               "nt:base.mode:localName": "",
               "nt:base.mode:depth": "0"
           },
           {
               "nt:base.jcr:primaryType": "mode:locks",
               "nt:base.jcr:path": "/jcr:system/mode:locks",
               "nt:base.jcr:name": "mode:locks",
               "nt:base.jcr:score": "0.3535533845424652",
               "nt:base.mode:localName": "locks",
               "nt:base.mode:depth": "2"
           }
       ]
    }