Search nodes

v1.0.0

Description:

Provides a flat list of file system nodes (rooms, folders or files) of a given parent that are accessible by the current user.

Precondition:

Authenticated user is allowed to 👁 see nodes (i.e. isBrowsable = true).

Postcondition:

List of nodes is returned.

Further Information:

Output is limited to 500 entries.
For more results please use filter criteria and paging (offset + limit).
EncryptionInfo is NOT provided.
Wildcard character is the asterisk character: *

Filtering:

All filter fields are connected via logical conjunction (AND)
Filter string syntax: FIELD_NAME:OPERATOR:VALUE[:VALUE...]

Example

type:eq:file|createdAt:ge:2015-01-01
Get nodes where type equals file AND file creation date is >= 2015-01-01.

Filtering options:

Expand

`FIELD_NAME`	Filter Description	`OPERATOR`	Operator Description	`VALUE`
`type`	Node type filter	`eq`	Node type equals value. Multiple values are allowed and will be connected via logical disjunction (OR). e.g. `type:eq:room:folder`	`room` `folder` `file`
`fileType`	File type filter (file extension)	`cn, eq`	File type contains / equals value.	`search String`
`classification`	Classification filter	`eq`	Classification equals value.	`1` - public `2` - internal `3` - confidential `4` - strictly confidential
`createdBy`	Creator login filter	`cn, eq`	Creator login contains / equals value (`firstName` OR `lastName` OR `email` OR `username`).	`search String`
`createdById`	Creator ID filter	`eq`	Creator ID equals value.	`positive Integer or -1 for external user`
`createdAt`	Creation date filter	`ge, le`	Creation date is greater / less equals than value. Multiple operator values are allowed and will be connected via logical conjunction (AND). e.g. `createdAt:ge:2016-12-31`\|`createdAt:le:2018-01-01`	`Date (yyyy-MM-dd)`
`updatedBy`	Last modifier login filter	`cn, eq`	Last modifier login contains / equals value (`firstName` OR `lastName` OR `email` OR `username`).	`search String`
`updatedById`	Last modifier ID filter	`eq`	Modifier ID equals value.	`positive Integer or -1 for external user`
`updatedAt`	Last modification date filter	`ge, le`	Last modification date is greater / less equals than value. Multiple operator values are allowed and will be connected via logical conjunction (AND). e.g. `updatedAt:ge:2016-12-31`\|`updatedAt:le:2018-01-01`	`Date (yyyy-MM-dd)`
`expireAt`	Expiration date filter	`ge, le`	Expiration date is greater / less equals than value. Multiple operator values are allowed and will be connected via logical conjunction (AND). e.g. `expireAt:ge:2016-12-31`\|`expireAt:le:2018-01-01`	`Date (yyyy-MM-dd)`
`size`	Node size filter	`ge, le`	Node size is greater / less equals than value. Multiple operator values are allowed and will be connected via logical conjunction (AND). e.g. `size:ge:5`\|`size:le:10`	`size in bytes`
`isFavorite`	Favorite filter	`eq`		`true or false`
`branchVersion`	Node branch version filter	`ge, le`	Branch version is greater / less equals than value. Multiple operator values are allowed and will be connected via logical conjunction (AND). e.g. `branchVersion:ge:1423280937404`\|`branchVersion:le:1523280937404`	`version number`
`parentPath`	Parent path	`cn, eq`	Parent path contains / equals value.	`search String`
`timestampCreation`	Creation timestamp filter	`ge, le`	Creation timestamp is greater / less equals than value. Multiple operator values are allowed and will be connected via logical conjunction (AND). e.g. `timestampCreation:ge:2016-12-31T23:00:00.123`\| `timestampCreation:le:2018-01-01T11:00:00.540`	`Date (yyyy-MM-dd)`
`timestampModification`	Modification timestamp filter	`ge, le`	Modification timestamp is greater / less equals than value. Multiple operator values are allowed and will be connected via logical conjunction (AND). e.g. `timestampModification:ge:2016-12-31T23:00:00.123`\| `timestampModification:le:2018-01-01T11:00:00.540`	`Date (yyyy-MM-dd)`
`referenceId`	Reference ID filter	`eq`	Reference ID equals value.	`Integer`

Sorting:

Sort string syntax: FIELD_NAME:ORDER
ORDER can be asc or desc.
Multiple sort criteria are possible.
Fields are connected via logical conjunction AND.

Example

name:desc|size:asc
Sort by name descending AND size ascending.

Sorting options:

Expand

`FIELD_NAME`	Description
`name`	Node name
`createdAt`	Creation date
`createdBy`	Creator first name, last name
`updatedAt`	Last modification date
`updatedBy`	Last modifier first name, last name
`fileType`	File type (extension)
`classification`	Classification ID: 1 - public 2 - internal 3 - confidential 4 - strictly confidential
`size`	Node size
`cntDeletedVersions`	Number of deleted versions of this file / folder (NOT recursive; for files and folders only)
`type`	Node type (room, folder, file)
`parentPath`	Parent path
`timestampCreation`	Creation timestamp
`timestampModification`	Modification timestamp

Deprecated sorting options:

Expand

`FIELD_NAME`	Description
~~`cntChildren`~~	Number of direct children (NOT recursive; for rooms and folders only)

Input

{
  "type": "object",
  "properties": {
    "X-Sds-Auth-Token": {
      "type": "string"
    },
    "X-Sds-Date-Format": {
      "type": "string",
      "enum": [
        "UTC",
        "LOCAL",
        "OFFSET",
        "EPOCH",
        "LEET"
      ]
    },
    "depth_level": {
      "type": "integer",
      "format": "int32"
    },
    "filter": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "format": "int32"
    },
    "offset": {
      "type": "integer",
      "format": "int32"
    },
    "parent_id": {
      "type": "integer",
      "format": "int64"
    },
    "search_string": {
      "type": "string"
    },
    "sort": {
      "type": "string"
    }
  },
  "required": [
    "search_string"
  ],
  "additionalProperties": false
}

Output

{
  "type": "object",
  "description": "List of nodes",
  "required": [
    "items",
    "range"
  ],
  "properties": {
    "items": {
      "type": "array",
      "description": "List of nodes",
      "items": {
        "type": "object",
        "description": "Node information (Node can be a room, folder or file)",
        "required": [
          "id",
          "name",
          "type"
        ],
        "properties": {
          "authParentId": {
            "type": "integer",
            "format": "int64",
            "description": "&#128640; Since v4.15.0\n\nAuth parent room ID"
          },
          "branchVersion": {
            "type": "integer",
            "format": "int64",
            "description": "Version of last change in this node or a node further down the tree."
          },
          "children": {
            "type": "array",
            "description": "&#128679; Deprecated since v4.10.0\n\nChild nodes list (if requested)\n\n(for rooms / folders only)",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "classification": {
            "type": "integer",
            "format": "int32",
            "description": "Classification ID:\n\n* `1` - public\n\n* `2` - internal\n\n* `3` - confidential\n\n* `4` - strictly confidential",
            "enum": [
              1,
              2,
              3,
              4
            ]
          },
          "cntChildren": {
            "type": "integer",
            "format": "int32",
            "description": "&#128679; Deprecated since v4.11.0\n\nNumber of direct children\n\n(no recursion; for rooms / folders only)"
          },
          "cntComments": {
            "type": "integer",
            "format": "int32",
            "description": "Returns the number of comments of this node."
          },
          "cntDeletedVersions": {
            "type": "integer",
            "format": "int32",
            "description": "Number of deleted versions of this file / folder\n\n(for rooms / folders only)"
          },
          "cntDownloadShares": {
            "type": "integer",
            "format": "int32",
            "description": "Returns the number of Download Shares of this node."
          },
          "cntFiles": {
            "type": "integer",
            "format": "int32",
            "description": "&#128640; Since v4.11.0\n\nAmount of direct child files where this node is the parent node\n\n(no recursion; for rooms / folders only)"
          },
          "cntFolders": {
            "type": "integer",
            "format": "int32",
            "description": "&#128640; Since v4.11.0\n\nAmount of direct child folders where this node is the parent node\n\n(no recursion; for rooms / folders only)"
          },
          "cntRooms": {
            "type": "integer",
            "format": "int32",
            "description": "&#128640; Since v4.11.0\n\nAmount of direct child rooms where this node is the parent node\n\n(no recursion; for rooms only)"
          },
          "cntUploadShares": {
            "type": "integer",
            "format": "int32",
            "description": "Returns the number of Upload Shares of this node."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Creation date"
          },
          "createdBy": {
            "type": "object",
            "description": "User information",
            "required": [
              "avatarUuid",
              "firstName",
              "id",
              "lastName",
              "userName",
              "userType"
            ],
            "properties": {
              "avatarUuid": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nAvatar UUID"
              },
              "displayName": {
                "type": "string",
                "description": "&#128679; Deprecated since v4.11.0\n\nDisplay name\n\nuse other fields from `UserInfo` instead to combine a display name"
              },
              "email": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nEmail "
              },
              "firstName": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nUser first name (mandatory if `userType` is `internal`)"
              },
              "id": {
                "type": "integer",
                "format": "int64",
                "description": "Unique identifier for the user"
              },
              "lastName": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nUser last name (mandatory if `userType` is `internal`)"
              },
              "title": {
                "type": "string",
                "description": "&#128679; Deprecated since v4.18.0\n\nJob title"
              },
              "userName": {
                "type": "string",
                "description": "&#128640; Since v4.13.0\n\nUsername (only returned for `internal` users)"
              },
              "userType": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nUser type:\n\n* `internal` - ordinary DRACOON user\n\n* `external` - external user without DRACOON account\n\n* `system` - system user (non human &#128125;)\n\n* `deleted` - deleted DRACOON user",
                "enum": [
                  "system",
                  "internal",
                  "external",
                  "deleted"
                ]
              }
            }
          },
          "encryptionInfo": {
            "type": "object",
            "description": "Encryption states",
            "required": [
              "dataSpaceKeyState",
              "roomKeyState",
              "userKeyState"
            ],
            "properties": {
              "dataSpaceKeyState": {
                "type": "string",
                "description": "DRACOON key state",
                "enum": [
                  "none",
                  "available",
                  "pending"
                ]
              },
              "roomKeyState": {
                "type": "string",
                "description": "Room key state",
                "enum": [
                  "none",
                  "available",
                  "pending"
                ]
              },
              "userKeyState": {
                "type": "string",
                "description": "User key state",
                "enum": [
                  "none",
                  "available",
                  "pending"
                ]
              }
            }
          },
          "expireAt": {
            "type": "string",
            "format": "date-time",
            "description": "Expiration date"
          },
          "fileType": {
            "type": "string",
            "description": "File type / extension (for files only)"
          },
          "hasActivitiesLog": {
            "type": "boolean",
            "description": "Is activities log active (for rooms only)"
          },
          "hash": {
            "type": "string",
            "description": "MD5 hash of file"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Node ID"
          },
          "inheritPermissions": {
            "type": "boolean",
            "description": "Inherit permissions from parent room\n\n(default: `false` if `parentId` is `0`; otherwise: `true`)"
          },
          "isBrowsable": {
            "type": "boolean",
            "description": "&#128640; Since v4.11.0\n\nDetermines whether node is browsable by client (for rooms only)"
          },
          "isEncrypted": {
            "type": "boolean",
            "description": "Encryption state"
          },
          "isFavorite": {
            "type": "boolean",
            "description": "Node is marked as favorite (for rooms / folders only)"
          },
          "mediaToken": {
            "type": "string",
            "description": "Media server media token"
          },
          "mediaType": {
            "type": "string",
            "description": "File media type (for files only)"
          },
          "name": {
            "type": "string",
            "description": "Name"
          },
          "notes": {
            "type": "string",
            "description": "User notes"
          },
          "parentId": {
            "type": "integer",
            "format": "int64",
            "description": "Parent node ID (room or folder)"
          },
          "parentPath": {
            "type": "string",
            "description": "Parent node path\n\n`/` if node is a root node (room)"
          },
          "permissions": {
            "type": "object",
            "description": "Node permissions",
            "required": [
              "change",
              "create",
              "delete",
              "deleteRecycleBin",
              "manage",
              "manageDownloadShare",
              "manageUploadShare",
              "read",
              "readRecycleBin",
              "restoreRecycleBin"
            ],
            "properties": {
              "change": {
                "type": "boolean",
                "description": "User / Group may update metadata of nodes: rename files and folders, change classification, etc."
              },
              "create": {
                "type": "boolean",
                "description": "User / Group may upload files, create folders and copy / move files to this room, overwriting is not possible."
              },
              "delete": {
                "type": "boolean",
                "description": "User / Group may overwrite and remove files / folders, move files from this room."
              },
              "deleteRecycleBin": {
                "type": "boolean",
                "description": "User / Group may permanently remove files / folders from the recycle bin."
              },
              "manage": {
                "type": "boolean",
                "description": "User / Group may grant all of the above permissions to other users and groups independently,\n\nmay update room metadata and create / update / delete subordinary rooms, has all permissions."
              },
              "manageDownloadShare": {
                "type": "boolean",
                "description": "User / Group may create Download Shares for files and containers view all previously created Download Shares in this room."
              },
              "manageUploadShare": {
                "type": "boolean",
                "description": "User / Group may create Upload Shares for containers, view all previously created Upload Shares in this room."
              },
              "read": {
                "type": "boolean",
                "description": "User / Group may see all rooms, files and folders in the room and download everything, copy files from this room."
              },
              "readRecycleBin": {
                "type": "boolean",
                "description": "User / Group may look up files / folders in the recycle bin."
              },
              "restoreRecycleBin": {
                "type": "boolean",
                "description": "User / Group may restore files / folders from recycle bin - room permissions required."
              }
            }
          },
          "quota": {
            "type": "integer",
            "format": "int64",
            "description": "Quota in byte"
          },
          "recycleBinRetentionPeriod": {
            "type": "integer",
            "format": "int32",
            "description": "Retention period for deleted nodes in days"
          },
          "referenceId": {
            "type": "integer",
            "format": "int64",
            "description": "&#128640; Since v4.37.0\n\nReference ID. Identical across all versions of a file"
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Node size in byte"
          },
          "timestampCreation": {
            "type": "string",
            "format": "date-time",
            "description": "&#128640; Since v4.22.0\n\nTime the node was created on external file system"
          },
          "timestampModification": {
            "type": "string",
            "format": "date-time",
            "description": "&#128640; Since v4.22.0\n\nTime the content of a node was last modified on external file system"
          },
          "type": {
            "type": "string",
            "description": "Node type",
            "enum": [
              "room",
              "folder",
              "file"
            ]
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Modification date"
          },
          "updatedBy": {
            "type": "object",
            "description": "User information",
            "required": [
              "avatarUuid",
              "firstName",
              "id",
              "lastName",
              "userName",
              "userType"
            ],
            "properties": {
              "avatarUuid": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nAvatar UUID"
              },
              "displayName": {
                "type": "string",
                "description": "&#128679; Deprecated since v4.11.0\n\nDisplay name\n\nuse other fields from `UserInfo` instead to combine a display name"
              },
              "email": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nEmail "
              },
              "firstName": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nUser first name (mandatory if `userType` is `internal`)"
              },
              "id": {
                "type": "integer",
                "format": "int64",
                "description": "Unique identifier for the user"
              },
              "lastName": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nUser last name (mandatory if `userType` is `internal`)"
              },
              "title": {
                "type": "string",
                "description": "&#128679; Deprecated since v4.18.0\n\nJob title"
              },
              "userName": {
                "type": "string",
                "description": "&#128640; Since v4.13.0\n\nUsername (only returned for `internal` users)"
              },
              "userType": {
                "type": "string",
                "description": "&#128640; Since v4.11.0\n\nUser type:\n\n* `internal` - ordinary DRACOON user\n\n* `external` - external user without DRACOON account\n\n* `system` - system user (non human &#128125;)\n\n* `deleted` - deleted DRACOON user",
                "enum": [
                  "system",
                  "internal",
                  "external",
                  "deleted"
                ]
              }
            }
          }
        }
      }
    },
    "range": {
      "type": "object",
      "description": "Range information",
      "required": [
        "limit",
        "offset",
        "total"
      ],
      "properties": {
        "limit": {
          "type": "integer",
          "format": "int64",
          "description": "Range limit. Maximum 500."
        },
        "offset": {
          "type": "integer",
          "format": "int64",
          "description": "Range offset"
        },
        "total": {
          "type": "integer",
          "format": "int64",
          "description": "Total items available"
        }
      }
    }
  }
}