Folders and Deletion

Data containers organize objects into folders. Each data object or folder can exist within one parent folder, and the system prevents circular references. The root folder, designated by the path /, serves as the default location for new objects and cannot be moved, cloned, or removed.

The system treats consecutive / characters as a single / and ignores trailing / characters in folder paths. You can rename, move, and remove folders as needed.

Folder Naming Requirements

Individual folder names have the following requirements:

• Must contain between 1 and 2,048 characters in UTF-8 encoding.

• Cannot be . or ...

• Cannot include control characters (matching the regular expression [\x00-\x1F]).

Complete folder paths have the following requirements:

• Must be under 10,240 characters total.

• Cannot exceed 128 nested folder levels. That is the root folder / with up to 128 subfolders.

Deletion of Data

When you remove data objects, the system automatically removes any hidden linked objects that can no longer be reached from other visible objects in the same data container through one or more links. For detailed information about object details, links, and visibility, see Details and Links and Visibility.

You can remove objects in any state, but this action cannot be undone. Removing open objects may cause additional effects, such as making upload URLs invalid. To remove objects, use either the /class-xxxx/removeFolder or /class-xxxx/removeObjects API methods.

API Methods

API method: /class-xxxx/newFolder

Specification

Creates a new folder in the data container using the given path.

Inputs

• folder string (required) The new folder to be created in the data container. Must meet the folder naming requirements.

• parents boolean (optional) Whether the parent folders should be created if they do not exist. Defaults to false.

Outputs

• id string ID of the manipulated data container.

Errors

• InvalidInput (the input is not a hash, or folder is missing or is not a nonempty string starting with "/", or parents is present but is not a boolean)

• ResourceNotFound (the specified data container does not exist, or parents is false but the parent folder of the folder specified in folder does not yet exist)

• InvalidState (a folder with the given path already exists and parents was not set to true)

• PermissionDenied (UPLOAD access required)

API method: /class-xxxx/renameFolder

Specification

Renames a current folder in the data container with the given name.

Inputs

• folder string (required) Folder to be renamed.

• name string (required) The new name of the folder (to replace the string after the last "/" in folder). Must meet the folder naming requirements.

Outputs

• id string ID of the manipulated data container.

Errors

• InvalidInput (the input is not a hash, or folder is missing or is not a nonempty string starting with "/", folder is "/", name is missing or is not a nonempty string with no "/")

• ResourceNotFound (the specified data container does not exist, or the specified folder does not exist)

• InvalidState (a folder with the given path already exists)

• PermissionDenied (CONTRIBUTE access required)

API method: /class-xxxx/listFolder

Specification

Lists the contents of a given data container's folder. Only folders or only objects can be specified to be returned, though this method returns both folders and objects by default. This method does not return hidden objects unless includeHidden is set to true.

Inputs

• folder string (optional) The folder to be listed. Defaults to "/".

• describe boolean or mapping (optional) Controls whether additional metadata is retrieved with data object results. Defaults to false. If true, equivalent to passing an empty mapping.

  • If a mapping, represents the input that would be used for calling the result's corresponding describe method.

• only string (optional) Indicates what type of contents to return. Defaults to "all".

  • Must be one of "folders", "objects", or "all".

• includeHidden boolean (optional) Whether hidden objects should be returned in objects. Applicable only if only is set to "objects" or "all". Defaults to false.

• hasSubfolderFlags boolean (optional) Whether folders in the output include subfolder flags. Defaults to false.

Outputs

• objects array of mappings List of metadata for all data objects in the specified folder. Each mapping contains:

  • id string The object ID.

  • describe mapping The output of the result's corresponding describe method.

    • Only present when describe was set in the input.

• folders array of strings or array of arrays List of all folders directly under the specified folder.

  • If hasSubfolderFlags is false (default), an array of folder name strings.

  • If hasSubfolderFlags is true, each element is a two-element array containing the folder name (string) and whether it has subfolders (boolean).

Errors

• InvalidInput

  • The input is not a hash

  • folder is not a nonempty string starting with "/"

  • only is given but is not one of "folders", "objects", and "all"

  • includeHidden is present but is not a boolean

• ResourceNotFound

  • The specified data container does not exist

  • A folder with the given path does not exist

• PermissionDenied (VIEW access required)

API method: /class-xxxx/removeFolder

Specification

Removes the given folder in the data container using the given path. The folder must contain no visible data objects to be removed unless recurse is set to true. Removing the root folder "/" with recurse set to true removes ALL the contents in the data container. Setting recurse to true should be used carefully to prevent accidental deletion of data. Removing a folder removes all the visible objects contained in it and all their orphaned hidden links. Any remaining hidden objects that are not removed by this process are placed in the root folder. In particular, if recurse is false and the folder to be removed only contains hidden objects, then these objects are similarly placed in the root folder, and the specified folder folder is removed.

The API call has a limit of 10,000 data objects that can be removed regardless of visibility. If a folder's contents goes above this threshold, one can set partial to true to allow for a partial removal of the folder's contents up to this limit. A completed flag in the output indicates whether the folder was fully removed. If completed is false, reissue the API call with the partial flag to continue removing the folder.

Inputs

• folder string (required) The folder to be removed from the data container.

• recurse boolean (optional) Whether removal should propagate to its contained folders and objects. Defaults to false.

• force boolean (optional) If true, this operation does not throw an error even if the given folder does not exist. Defaults to false.

• partial boolean (optional) If true, this operation attempts to remove objects from the folder even if the folder contains more objects than can be deleted at one time. Defaults to false.

Outputs

• id string ID of the manipulated data container.

• completed boolean Whether all objects, subfolders, and the specified folder have been removed. If false, reissue the API call to continue removal.

  • Only present when partial was set to true.

Errors

• InvalidInput (the input is not a hash, folder is missing, folder is not set to a nonempty string starting with "/", folder is set to "/" but recurse is not specified or is false, recurse is provided and is not a boolean)

• ResourceNotFound

  • The specified data container does not exist

  • A folder with the given path does not exist and force was not set to true

• PermissionDenied (CONTRIBUTE access required)

• InvalidState

  • The project contains a DBCluster in a non-terminal state

  • recurse is false and the specified folder contains either subfolders or visible objects

  • partial is false and the specified folder contains more objects than can be deleted in one API call. For more information, see Service Limits.

API method: /class-xxxx/move

Specification

Moves the specified objects and/or folders into the specified folder. Objects and folders can be moved from any state and any folder in the data container. Objects and folders in a folder listed in folders remain in the (moved) folder unless explicitly listed in objects or folders. In that case, they are removed from their parent folder and moved to the destination folder described in folder. Objects explicitly listed in objects also move any linked hidden objects to the folder indicated as destination.

Inputs

• objects array of strings (optional) List of data object IDs to be moved.

• folders array of strings (optional) List of folders to be moved.

• destination string (required) The destination folder.

Outputs

• id string ID of the manipulated data container.

Errors

• InvalidInput (the input is not a hash, objects (if provided) is not an array of nonempty strings, folders (if provided) is not an array of nonempty strings starting with "/", two of the folders in folders have the same name but different paths, destination is missing or is not a nonempty string starting with "/")

• ResourceNotFound (the specified data container does not exist, one of the specified objects and/or folders does not exist in the specified data container, or the destination folder does not exist)

• PermissionDenied (CONTRIBUTE access required)

• InvalidState (a folder listed in folders is or contains the destination folder)

API method: /class-xxxx/removeObjects

Specification

Removes the specified objects from the data container. When you remove objects, the system also removes any hidden linked objects that can no longer be reached from other visible objects in the same data container through one or more links. You can remove objects in any state, but this action cannot be undone.

Removing open objects may cause additional effects, such as making upload URLs invalid. To restore a removed object to the data container, you must have a copy in another data container and the proper permissions to clone it back. When cloning an object back, any previously set custom metadata is lost and replaced with metadata from the source data container. For more information, see Cloning.

Inputs

• objects array of strings (required) List of object IDs to be removed from the data container.

• force boolean (optional) If true, this operation does not throw an error even if the given object does not exist. Defaults to false.

Outputs

• id string ID of the manipulated data container.

Errors

• InvalidInput (the input is not a hash, or objects is missing or is not an array of nonempty strings)

• ResourceNotFound

  • The specified data container does not exist

  • An object with the given ID does not exist or does not exist in the specified data container and force was not set to true

• PermissionDenied (CONTRIBUTE/ADMINISTER access required, depending on PROTECTED flag)

• InvalidState

  • One of the objects is a DBCluster in a non-terminal state