# REST - Folder Management

Management of the folder and report tree is available with REST. Unlike other resources, managing the tree affects the base configuration, and is not temporary to a session. Therefore it also affects concurrent users.

> Note. All requests require Session Id URL parameter and basic request headers. In the following examples, headers are omitted for clarity.

# Node JSON

The folders tree is represented as an output-only (ie. non-writeable) resource. Each object in the tree is a Node. Nodes are represented as JSON objects with the following properties:

Name | Type | Description
name | string | The name of this folder or report
leaf_flag | boolean | Whether this node is a report
readonly_flag | boolean | Whether this node is read-only for the active role
type | enum | Report Type (null if this is a folder)
user | string | The active role
entity | array of Node | If this is a folder, an array of the nodes contained within

> Note. The top-level node has only an entity property.

### Example

    {
      "entity": [
        {
          "name":          "Asset Reports",
          "leaf_flag":     false,
          "readonly_flag": false,
          "type":          null,
          "user":          "Admin",
          "entity": [
            {
              "name":          "Sales Report",
              "leaf_flag":     true,
              "readonly_flag": false,
              "type":          "advanced",
              "user":          "Admin",
              "entity":        null
            },
            {
              "name":          "Financial Holdings",
              "leaf_flag":     false,
              "readonly_flag": false,
              "type":          null,
              "user":          "Admin",
              "entity": [
                {
                  "name":          "Liquidity Report",
                  "leaf_flag":     true,
                  "readonly_flag": false,
                  "type":          "expressview",
                  "user":          "Admin",
                  "entity":        null
                },
                {
                  "name":          "Regional Holdings",
                  "leaf_flag":     true,
                  "readonly_flag": false,
                  "type":          "dashboard",
                  "user":          "Admin",
                  "entity":        null
                }
              ]
            }
          ]
        }
      ]
    }

# Show Folders Tree

    GET /rest/reports/list

Show the full folder tree for the current configuration.

### Using curl

    curl http://{webservice}/rest/reports/list?sid={sid} -X GET

### Example response

    Status: 200 OK

    {
      "entity": [
        {
          "name": "Asset Reports",
          ...
          "entity": [
            {
              "name": "Sales Report",
              ...
              "entity": null
            },
            {
              "name": "Financial Holdings",
              ...
              "entity": [
                {
                  "name": "Liquidity Report",
                  ...
                  "entity": null
                }
              ]
            }
          ]
        }
      ]
    }

# Folder JSON

The /rest/folders endpoint represents each folder as an output-only (ie. non-writeable) resource. Folders are represented as JSON objects with the following properties:

Name | Type | Description
Name | string | Full path from root folder to this folder
Status | const | Folder Status

# Create a Folder

    POST /rest/folders/{Name}

Name is the full path from the root folder to the name of the folder to be created. Spaces and unusual characters must be URL-encoded. Folder names are case sensitive.

### Using curl

    curl http://{webservice}/rest/folders/Asset%20Reports/Overseas%Holdings?sid={sid} -X POST

### Example response

    Status: 200 OK

    {
      "Id":     null,
      "Name":   "Asset Reports/Overseas Holdings",
      "Status": "Created"
    }

> Note. The "Id" property is not used.

# Move or Rename a Folder

    POST /rest/folders/rename

Folders are moved or renamed by supplying the following JSON resource:

Name | Type | Writeable | Description
OldName | string | required | Full path from the root folder to the name of the folder to be moved or renamed
NewName | string | required | Full path from the root folder to the new folder location and name

### Using curl

    curl http://{webservice}/rest/folders/rename?sid={sid} -X POST ^
    	-d "{'OldName':'Asset Reports\\Overseas Holdings', ^
    	'NewName':'Asset Reports\\Regional Holdings'}"

> Note. Windows file paths are delineated by double-backslashes: \\

### Example response

    Status: 200 OK

    {
      "Id":     null,
      "Name":   "Asset Reports/Regional Holdings",
      "Status": "Renamed"
    }

# Delete a Folder

    DELETE /rest/folders/{Name}

Name is the full path from the root folder to the name of the folder to be created. Spaces and unusual characters must be URL-encoded. Folder names are case sensitive. The folder must be empty to be deleted.

### Using curl

    curl http://{webservice}/rest/folders/Asset%20Reports/Overseas%Holdings?sid={sid} -X DELETE

### Example response

    Status: 200 OK

    {
      "Id":     null,
      "Name":   "Asset Reports/Overseas Holdings",
      "Status": "Deleted"
    }