Skip to end of metadata
Go to start of metadata

Represents the latest version of the RESTful API distributed with ModeShape 4.6.0. It provides the following methods:


1. Retrieve a list of available repositories

URL: http://<host>:<port>/<context>

HTTP Method: GET

Produces: application/json; text/html; text/plain;

Default Output: text/html

Response Code (if successful): OK

Response Format:


2. Retrieve a list of workspaces for a repository

URL: http://<host>:<port>/<context>/<repository_name>

HTTP Method: GET

Produces: application/json; text/html; text/plain;

Default Output: text/html

Response Code (if successful): OK

Response Format:


3. Retrieve a node or a property

Retrieves an item at a given path.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/items/<item_path>

HTTP Method: GET

Produces: application/json; text/html; text/plain;

Default Output: text/html

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

Response Format:


4. Create a node

Creates a node at the given path, using the body of request as JSON content

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/items/<node_path>

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Request Content-Type: application/json

Response Code (if successful): CREATED

Request Format:

Response Format:

Multiple properties with the same name
The different JSON specs that are out there have conflicting views on whether multiple keys with the same name should be allowed or not. See this for more information.

ModeShape's REST service follows the ECMA JSON specification, which allows multiple keys with the same name, the effective behavior being that the last key always wins.

Same Name Siblings

Because of the above, creating SNS children in a request cannot be done using a JSON object format for the children element. The REST service supports an alternative, array-based format:


5. 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>/<repository_name>/<workspace_name>/items/<item_path>

HTTP Method: PUT

Produces: application/json; text/html; text/plain;

Default Output: application/json

Request Content-Type: application/json

Response Code (if successful): OK

Request Format:

Node: same as the one used when creating

Property:

Response Format:

Node: same as one used when creating

Property:

Same Name Siblings

When updating the SNS children of a given node, 2 requests format are available:

  1. An array-based format similar to the one described for the "create" case:
  2. An object format where the name of each SNS contains its index:

6. Delete a node or a property

Deletes the node or the property at the given path. If a node is being deleted, this will also delete all of its descendants.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/items/<item_path>

HTTP Method: DELETE

Produces: none

Response Code (if successful): NO_CONTENT


7. Retrieve a node by its identifier

Retrieves a node with a specified identifier. This is equivalent to the Session.getNodeByIdentifier(String) method, where the identifier is obtained from the "id" field (or the "jcr:uuid" field if the node is mix:referenceable) in a previous response. Remember that node identifiers are generated by the repository, are opaque (and are not always UUIDs), and always remains the same for a given node (even when moved or renamed) until the node is destroyed.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/nodes/<node_id>

HTTP Method: GET

Produces: application/json; text/html; text/plain;

Default Output: text/html

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

Response Format:


8. Update a node by its identifier

Updates a node with the given identifier, using the body of request as JSON content. The identifier must be obtained from the "id" field in a previous response.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/nodes/<node_id>

HTTP Method: PUT

Produces: application/json; text/html; text/plain;

Default Output: application/json

Request Content-Type: application/json

Response Code (if successful): OK

Request Format:

Node: same as the one used when creating a node

Property:

Response Format:

Node: same as one used when creating a node

Property:


9. Delete a node by its identifier

Deletes the node with the given identifier, and all of its descendants. The identifier must be obtained from the "id" field in a previous response.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/nodes/<node_id>

HTTP Method: DELETE

Produces: none

Response Code (if successful): NO_CONTENT


10. 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>/<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: application/json

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:


11. Create multiple nodes

Creates multiple nodes (bulk operation) in the repository, using a single session. If any of the nodes cannot be created, the entire operation fails.

URL: _http://<host>:<port>/<context>/<repository_name>/<workspace_name>/items

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Request Content-Type: application/json

Response Code (if successful): OK

Request Format:

Response Format:


12. Update multiple items

Updates multiple nodes and/or properties (bulk operation) in the repository, using a single session. If any of the items cannot be updated, the entire operation fails.

URL: _http://<host>:<port>/<context>/<repository_name>/<workspace_name>/items

HTTP Method: PUT

Produces: application/json; text/html; text/plain;

Default Output: application/json

Request Content-Type: application/json

Response Code (if successful): OK

Request Format: same as the one used when creating multiple nodes.

Response Format: same as the one used when creating multiple nodes.


13. Delete multiple items

Deletes multiple items (bulk operation) in the repository, using a single session. If any of the items cannot be removed, the entire operation fails.

URL: _http://<host>:<port>/<context>/<repository_name>/<workspace_name>/items

HTTP Method: DELETE

Produces: none;

Request Content-Type: application/json

Response Code (if successful): OK

Request Format:


14. Retrieve a node type

Retrieves the information about a registered node type in the repository.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/nodetypes/node_type_name

HTTP Method: GET

Produces: application/json; text/html; text/plain;

Default Output: text/html

Response Code (if successful): OK

Response Format:


15. Import a CND file (via request content)

Imports a CND file into the Repository, using the entire request body stream as the content of the CND. If you were using curl, this would be the equivalent of curl -d

URL: _http://<host>:<port>/<context>/<repository_name>/<workspace_name>/nodetypes

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Response Code (if successful): OK

Response Format:


16. Import a CND file (via "multipart/form-data")

Imports a CND file into the Repository when the CND file came from a form submission, where the name of the HTML element is file. If you were using curl, this would be the equivalent of curl -F

URL: _http://<host>:<port>/<context>/<repository_name>/<workspace_name>/nodetypes

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Request Content-Type: multipart/form-data

Default Output: application/json

Response Code (if successful): OK

Response Format: the same as when importing a CND via the request body.


17. Retrieve a binary property

Retrieves the content of a binary property from the repository, at a given path, by streaming it to the response.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/binary/binary_property_path

HTTP Method: GET

Produces: the mime-type of the binary, or a default mime-type

Response Code (if successful): OK

Optional Query Parameters:

  • mimeType - a string which can be provided by the client, in case it already knows the expected mimetype of the binary stream. Otherwise, ModeShape will try to detect the mimetype using its own detectors mechanism
  • contentDisposition - a string which will be returned as the Content-Disposition response header. If none provide, the default is: attachment;filename=property_parent_name

18. Create a binary property (via request content)

Creates a new binary property in the repository, at the given path, using the entire request body stream as the content of the binary. If you were using curl, this would be the equivalent of curl -d

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/binary/binary_property_path

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Response Code (if successful): OK

Response Format:


19. Update a binary property (via request content)

Updates the content of a binary property in the repository, at the given path, using the entire request body stream as the content of the binary. If you were using curl, this would be the equivalent of curl -d

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/binary/binary_property_path

HTTP Method: POST, PUT

Produces: application/json; text/html; text/plain;

Default Output: application/json

Response Code (if successful): OK

Response Format: the same as in the case when creating a new binary property


20. Create/Update a binary property (via "multipart/form-data")

Creates or updates the content of a binary property in the repository, at the given path, when the content came from a form submission, where the name of the HTML element is file.
If you were using curl, this would be the equivalent of curl -F

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/binary/binary_property_path

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Request Content-Type: multipart/form-data

Response Code (if successful): OK

Response Format: the same as in the case when creating a new binary property


21. Obtain a query plan for a JCR query

Obtain the query plan for an XPath, SQL or SQL2 query, returning the string representation of the query plan.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/queryPlan

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: text/plain

Request Content-Type: application/jcr+sql; application/jcr+xpath; application/jcr+sql2; application/jcr+search

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 (as "application/json"):

Note that the JSON response contains several fields, including the original query statement, the language, the abstract query model (or AQM, which is always equivalent to the JCR-SQL2 form of the query), and the query plan (as an array of strings).

Response Format (as "text/plain"):

The text response only contains the string representation of the query plan.


22. Reordering nodes

Assuming you create a parent node POSTing the following request:

Then you can reorder its children by issuing a PUT request with the following format:


23. Moving nodes

In order to move a node using the REST service, 2 steps are required:

  1. Retrieve the node which should be moved and store its ID (the id member of the JSON response)
  2. Edit the parent-to-be node (aka. the new parent) via a PUT request which contains the ID of the node:

24. Upload a binary (via request content) under a hierarchy of nodes

Uploads (create/updates) a binary property of a node as part of a hierarchy using the entire request body stream as the content of the binary, creating missing parts of the hierarchy. If you were using curl, this would be the equivalent of curl -d.
If any segment of the hierarchy does not exist, it will be created as an [nt:folder] node, while the last segment in the hierarchy, if it does not exist, will be created as an [nt:file] node.

If any segment in the hierarchy does exist it will not be created, but the binary value is always uploaded & added as property named [jcr:data] under a [jcr:content] child of the last node in the hierarchy.

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/upload/<path>

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Response Code (if successful): OK (if the binary property existed previously and was updated) or CREATED (if the binary property is created)

Example: executing POST http://localhost:8080/modeshape-rest/repo/default/upload/node1/node2/node3 on an empty repository, will create the hierarchy node1(nt:folder)/node2(nt:folder)/node3(nt:file)/jcr:content(nt:resource) under the root node and set the value of the jcr:data property of node3/jcr:content to the binary content read from the request body.

If this hierarchy existed previously with the same node types, the request will update the property replacing its binary content. If this hierarchy existed previously but with different node types, it is expected that node3 allows a child named [jcr:content] with a [jcr:data] property.

Using CURL: curl -X POST --data-binary @image.png --user admin:admin http://localhost:8080/modeshape-rest/sample/default/upload/image.png


25. Upload a binary (via "multipart/form-data") under a hierarchy of nodes

Uploads (create/updates) a binary property of a node as part of a hierarchy when the binary content comes from a form submission and the name of the HTML element is file, creating missing parts of the hierarchy.
If you were using curl, this would be the equivalent of curl -F

URL: http://<host>:<port>/<context>/<repository_name>/<workspace_name>/upload/<path>

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Request Content-Type: multipart/form-data

Response Code (if successful): OK (if the binary property existed previously and was updated) or CREATED (if the binary property is created)

The behavior is identical to that of the previous method (see above), the only difference being the content type of the request.

Using CURL: curl -X POST -F "file=@image.png" --user admin:admin http://localhost:8080/modeshape-rest/sample/default/upload/image.png


26. Backup a repository

Performs a repository backup on the server into one of the following locations (the first available one will be used):

  1. the backupLocation servlet context parameter, if defined in the web.xml configuration file of the web application which contains the REST Service
  2. the value of the jboss.domain.data.dir system property (is normally available when running a JBoss Application Server in domain mode). If available defaults to ${JBOSS_HOME}/domain/data.
  3. the value of the jboss.standalone.data.dir system property (is normally available when running a JBoss Application Server in standalone mode). If available defaults to ${JBOSS_HOME}/standalone/data.
  4. the value of the user.home system property

URL: http://<host>:<port>/<context>/<repository_name>/backup

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Response Code (if successful): CREATED

Using CURL: curl -X POST --user dnauser:password http://localhost:8090/resources/repo/backup will produce:

There are also a number of optional request parameters which can be passed to control the backup behavior:

Parameter Default Description
includeBinaries true Whether binary values should be included in the backup or not. If your repository has a large amount of binary values, you may want to exclude them since it can cause the backup to take a very long time
documentsPerFile 100000 The number of documents (i.e. entries stored by ModeShape in Infinispan) to be included in each backup file
compress true Whether or not each file containing documents should be compressed or not

27. Restore a repository

Performs a repository restore on the server by using the name of the given backup folder and searching for it into one of the following locations (the first available one will be used):

  1. the backupLocation servlet context parameter, if defined in the web.xml configuration file of the web application which contains the REST Service
  2. the value of the jboss.domain.data.dir system property (is normally available when running a JBoss Application Server in domain mode). If available defaults to ${JBOSS_HOME}/domain/data.
  3. the value of the jboss.standalone.data.dir system property (is normally available when running a JBoss Application Server in standalone mode). If available defaults to ${JBOSS_HOME}/standalone/data.
  4. the value of the user.home system property

The name of the backup folder should be retrieved from the response of the repository backup request (see above).

URL: http://<host>:<port>/<context>/<repository_name>/restore?name=<backup_folder>

HTTP Method: POST

Produces: application/json; text/html; text/plain;

Default Output: application/json

Response Code (if successful): OK

Using CURL: curl -X POST --user dnauser:password http://localhost:8090/resources/repo/restore?name=modeshape_43-SNAPSHOT_repo_backup_07042015_111243

There are also a number of optional request parameters which can be passed to control the restore behavior:

Parameter Default Description
name none, you must provide it The name of a backup folder on the server which will be used as the source of the data
includeBinaries true Whether binary values should be restored from the backup folder or not
reindexContent true Whether or not a reindexing of the content should be performed once the restore is complete. If the backup contains lots of data and you already have accurate indexes created prior to the backup, you may want to skip this
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.