3.4 Folders

3.4.1 Create folder

The "child_library_folders" link of the parent folder is used to create a new folder.  For example, take the following folder listing:


[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/self/my_files/library_children

[Response]
{
  "first": 0,
  "count": 24,
  "total": 24,
  "items": [{
    "id": 48,
    "doc_type": "binder",
    "entity_type": "folder",
    "href": "/folders/48",
    "title": "A",
    "links":[{
      "rel": "child_library_folders",
      "href": "/folders/48/library_folders"
    },...],
    ...
  },...
}

The "child_library_folders" location for this folder is "/folders/48/library_folders".  To create a subfolder, POST a Folder object to that resource.  The only required field in the Folder object is the title:


[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/48/library_folders \
  -X POST -H "Content-Type: application/json" -d '{"title": "AA"}'

[Response]
{
  "id":82,
  "title":"AA",
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:30:10Z"},
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:30:10Z"},
  "path":"/Home Workspace/Personal Workspaces/David Lewis (dlewis)/Home/A/AA",
  "library":true,
  "mirrored":true,
  "href":"/folders/82",
  "links":[...],
  "doc_type":"binder",
  "parent_binder":{"id":48,"href":"/binders/48"},
  "entity_type":"folder"
}

The response is the newly created Folder object.

If a subfolder with that name already exists, the server will return an HTTP 409 Conflict status code.  The response body will be an ErrorInfo object with a "TITLE_EXISTS" code and the existing Folder resource:


[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/48/library_folders \
  -X POST -H "Content-Type: application/json" -d '{"title": "AA"}'

[Response]
{
  "code": "TITLE_EXISTS",
  "message: "Title already exists: AA",
  "data": {
    "id":82,
    "title":"AA",
    "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:30:10Z"},
    "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:30:10Z"},
    "path":"/Home Workspace/Personal Workspaces/David Lewis (dlewis)/Home/A/AA",
    "library":true,
    "mirrored":true,
    "href":"/folders/82",
    "links":[...],
    "doc_type":"binder",
    "parent_binder":{"id":48,"href":"/binders/48"},
    "entity_type":"folder"
  }
}

3.4.2 Rename folder

To rename a folder, use the "title" related link of the Binder object (href: "/folders/{id}/title").  The Content-Type must be "application/x-www-form-urlencoded" and the new name of the folder is specified by the "title" form parameter.  The REST interface returns the full Binder resource in the response.


[Request]
> curl -k -u dlewis:novell "https://amethyst.provo.novell.com:8443/rest/folders/82/title" 
  -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "title=AA%20renamed"

[Response]
{
  "id":82, 
  "title":"AA renamed", 
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:30:10Z"}, 
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:46:49Z"}, 
  "path":"/Home Workspace/Personal Workspaces/David Lewis (dlewis)/Home/A/AA renamed", 
  "library":true, 
  "mirrored":true, 
  "href":"/folders/82", 
  "links":[...], 
  "doc_type":"binder", 
  "parent_binder":{"id":48,"href":"/binders/48"}, 
  "entity_type":"folder"
}

The title in the POST form data should be a UTF-8 string that has been URL encoded.

3.4.3 Move folder

To move a folder, use the "parent_binder" related link of the Binder object (href: "/folders/{id}/parent_binder").  The Content-Type must be "application/x-www-form-urlencoded" and the target folder is specified by the "binder_id" form parameter.  The REST interface returns the full Binder resource in the response.


[Request]
> curl -k -u dlewis:novell "https://amethyst.provo.novell.com:8443/rest/folders/82/parent_binder" 
  -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "binder_id=49"

[Response]
{
  "id":82, 
  "title":"AA renamed", 
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:30:10Z"}, 
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T22:46:49Z"}, 
  "path":"/Home Workspace/Personal Workspaces/David Lewis (dlewis)/Home/A/AA renamed", 
  "library":true, 
  "mirrored":true, 
  "href":"/folders/82", 
  "links":[...], 
  "doc_type":"binder", 
  "parent_binder":{"id":49,"href":"/binders/49"}, 
  "entity_type":"folder"
}

3.4.4 Delete folder

To delete a folder, send DELETE request to the Folder resource's href location:


[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/82 -X DELETE

[Response]
< HTTP/1.1 204 No Content

If successful, the REST interface returns an HTTP 204 (No Content) status code with no response body.

For personal storage folders, the default behavior is to move the folder to the trash.  To delete the folder permanently, use the "purge=true" query parameter:


[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/82?purge=true -X DELETE

[Response]
< HTTP/1.1 204 No Content

Trash is not supported for external storage folders (mirrored/net folder).  They are always deleted permanently.

By default, this will delete the folder and its children.  To only delete the folder if it is empty, use the "only_if_empty=true" query parameter.  If the folder is not empty, the server will return an HTTP 409 Conflict status code.  The response body will be an ErrorInfo object with a "BINDER_NOT_EMPTY" code.


[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/82?only_if_empty=true -X DELETE

[Response]
< HTTP/1.1 409 Conflict
{"code":"BINDER_NOT_EMPTY","message":"The binder is not empty."}

3.4.5 Copy folder

The "child_library_folders" related link of a Folder can be used to copy another into that folder.  The Content-Type must be "application/x-www-form-urlencoded" and the source folder to be copied is specified by the "source_id" form parameter.  The name of the new folder is specified by the "title" form parameter.  The REST interface returns the Folder representation of the new folder in the response.

For example, the "child_library_folders" related link of the My Files top level folder is "/self/my_files/library_folders".  The following copies a folder there:


[Request]
> curl -k -u dlewis:novell "https://amethyst.provo.novell.com:8443/rest/self/my_files/library_folders" \
  -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "source_id=49&title=B%20copied"

[Response]
{  
  "id":83,
  "title":"B copied",
  "description":{"text":"","format":2,"format_str":"text"},
  "family":"file",
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T23:15:33Z"},
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-24T23:15:33Z"},
  "attachments":[],
  "path":"/Home Workspace/Personal Workspaces/David Lewis (dlewis)/Home/B copied",
  "library":true,
  "mirrored":true,
  "href":"/folders/83",
  "links":[...],
  "doc_type":"binder",
  "parent_binder":{"id":44,"href":"/binders/44"},
  "entity_type":"folder"
}