REST API Folders

Owned by Charles Bishop (Deactivated)
Last updated: Apr 27, 2021 by Juliane Wetzel
11 min read

Unlike other REST APIs, these use the file ID (found in the File Browser) or the UUID (found in all payloads or JSON representations) instead of the configuration ID.

The REST API for folders follows the best practices for RESTful API design. (warning) Make sure you read the HTTP status codes and interpret them together with the responses.

Note that overwrite functions adhere to the user’s existing permission settings. 

To receive more meaningful HTTP errors for each call, you can add the following command after the username and password:


-w"\n%{http_code}\n"

Read the Root Folder

Request method - GET

Description

Returns a list of all the folders in the folder tree in Datameer.

URI syntax

curl -u '<username>:<password>' -X GET 'http://<Datameer-serverIP>:<port-number>/api/filesystem/root-folder'

Example response

{
  "name": "/",
  "uuid": "f81eeb96-b675-4ace-878c-269962e03ca4",
  "_links": {
    "self": {
      "href": "/api/filesystem/root-folder"
    },
    "permission": {
      "href": "/api/filesystem/folders/1/permission"
    }
  },
  "_embedded": {
    "folders": [
      {
        "name": "Users",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/3"
          }
        }
      },
      {
        "name": "Data",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/4"
          }
        }
      },
      {
        "name": "Analytics",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/10"
          }
        }
      },
      {
        "name": "Visualization",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/12"
          }
        }
      },
      {
        "name": "Images",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/14"
          }
        }
      },
      {
        "name": ".system",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/2"
          }
        }
      },
      {
        "name": "Examples",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/18"
          }
        }
      }
    ]
  }

Read the Folder

Request method - GET

Description

Returns a list of the folder's content in Datameer.

URI syntax

curl -u '<username>:<password>' -X GET 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>'

Example response

{
  "name": "Data",
  "uuid": "9e6635dd-d02d-4073-9e6e-123a31c46938",
  "_links": {
    "parent": {
      "href": "/api/filesystem/folders/1"
    },
    "self": {
      "href": "/api/filesystem/folders/4"
    },
    "permission": {
      "href": "/api/filesystem/folders/4/permission"
    }
  },
  "_embedded": {
    "folders": [
      {
        "name": "Connections",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/5"
          }
        }
      },
      {
        "name": "ImportJobs",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/6"
          }
        }
      },
      {
        "name": "DataLinks",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/7"
          }
        }
      },
      {
        "name": "FileUploads",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/8"
          }
        }
      },
      {
        "name": "ExportJobs",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/9"
          }
        }
      }
    ]
  }

Read Folder Permissions

Request method - GET

Description

Returns a list of the folder's permissions in Datameer.

URI syntax

curl -u '<username>:<password>' -X GET 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission'

Example response

{
  "others": {
    "readable": true,
    "writable": true
  },
  "owner": "admin",
  "_links": {
    "folder": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938"
    },
    "others": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission/others"
    },
    "owner": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission/owner"
    },
    "self": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission"
    },
    "groups": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission/groups"
    }
  }

Read Group Permissions of a Folder

Request method - GET

Description

Returns a list of the folder's group permissions in Datameer.

URI syntax

curl -u '<username>:<password>' -X GET 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission/groups'

Example response

{
  "_links": {
    "self": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission/groups"
    },
    "permission": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission"
    }
  },
  "_embedded": {
    "groups": [
      {
        "flags": {
          "readable": true,
          "writable": true
        },
        "name": "dasuser",
        "_links": {
          "self": {
            "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission/groups/dasuser"
          },
          "permission": {
            "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission"
          }
        }
      }
    ]
  }

Read Other Permissions of a Folder

Request method - GET

Description

Returns a list of the folder's permissions for others in Datameer.

URI syntax

curl -u '<username>:<password>' -X GET 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission/others

Example response

{
  "readable": true,
  "writable": true,
  "_links": {
    "self": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission/others"
    },
    "permission": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission"
    }
  }

Read the Owner of a Folder

Request method - GET

Description

Returns a list of the folder's owners in Datameer.

URI syntax

curl -u '<username>:<password>' -X GET 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission/owner'

Example response

{
  "owner": "admin",
  "_links": {
    "self": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission/owner"
    },
    "permission": {
      "href": "/api/filesystem/folders/9e6635dd-d02d-4073-9e6e-123a31c46938/permission"
    }
  }

Change the Owner of a Folder

Request method - PUT

Description

Changes the owner of folder in Datameer.

URI syntax

curl -u '<username>:<password>' -X PUT -H "Content-Type:application/json" -H "Accept: application/json"  -d "{owner:<username>}" "http://
<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id>/permission/owner"

Verification

Check through a REST command or in the File Browser.

Create a Group Permission for a Folder

Request method - POST

Description

Sets permissions for groups for a folder created in Datameer.

URI syntax

curl -u '<username>:<password>' -X POST -H  'Content-Type:application/json' -d '{name="<group>\",flags:{executable:<true> or <false>,readable:<true> or <false>,writable:<true> or <false>}}' 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission/groups'

Verification

Check through REST command or in the browser.

Change Group Permission for a Folder

Request method - PUT

Description

Changes permissions for groups for a folder created in Datameer.

URI syntax

curl -u '<username>:<password>' -X PUT -H 'Content-Type:application/json' -d 'name="<group>\",flags:{executable:<false> or <true>,readable:<false> or <true>,writable:<false> or <true>}}' 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission/groups/<group>'

Verification

Check through a REST command or in the File Browser.

Change Others Permission for a Folder

Request method - PUT

Description

Changes permissions for others for a folder in Datameer.

URI syntax

curl -u '<username>:<password>' -X PUT -H "Content-Type:application/json" -d '{executable:<false> or <true>,readable:<false> or <true>,writable:<false> or <true>}' http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission/others

Verification

Check through a REST command or in the File Browser.

Delete Group Permission of a Folder

Request method - DELETE

Description

Deletes the group permissions of a folder in Datameer.

URI syntax

curl -u '<username>:<password>' -X DELETE -H 'Content-Type:application/json' 'http://<Datameer-serverIP>:<port-number>/api/filesystem/folders/<file-id> or <uuid>/permission/groups/<group>'

Verification

Check through a REST command or in the File Browser.

Download a Folder as a ZIP File

Request method - GET

Description

Downloads the folder and all its contents including sub folders and their contents. 

URI syntax

curl -u <username>:<password> -X GET -o <name>.zip 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/backup'

To find a folder using the path, the path needs to be URL encoded, (e.g., use %2F for a / and %20 for a ' ' (space).)

Verification

The ZIP file downloaded is located in the directory the REST call was given. 

Advanced parameters

Backup-ignoreDependencies

Allows for backing up a project where the data sources (for example) are not contained within the same folder as the rest of the project.

URI syntax

curl -u <username>:<password> -X GET -o <name>.zip 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/backup?ignoreMissingDependencies'

Backup-Skip

Disregards entities where dependencies are contained outside of the folder to backup, these files aren't written to the zip file.

URI syntax

curl -u <username>:<password> -X GET -o <name>.zip 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/backup?skipFilesWithMissingDependencies'

Download a Specific File as a ZIP File

Available as of Datameer 7.2.6

Request method - POST

Description

Downloads a specific file from a folder. 

Preparation 

To download a specific file from a folder, you need to create and save a JSON file that is used to locate the file you want to download.

JSON example using the file path:

{
  "ids": [
    "/path/to.wbk"
  ]
}
JSON example using the file-id:
{
  "ids": [
    23
  ]
}
JSON example using the uuid:
{
  "ids": [
    "17c8d988-d771-435f-a381-31bba6fba34d"
  ]
}

URI syntax

curl -u <username>:<password> -X POST --data-binary @<pathToJsonFile> -H 'Content-Type: application/json' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>|<file-id>|<UUID>/backup' -o <name>.zip

To find a folder using the path, the path needs to be URL encoded, (e.g., use %2F for a / and %20 for a ' ' (space).)

Verification

The ZIP file downloaded is located in the directory the REST call was given. 


Migrate/Restore a Folder from a ZIP File

Request method - PUT


Description

Uploads the folder and all its contents including sub-folders and their contents. 

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/restore'

To find a folder using the path, the path needs to be URL encoded, (e.g., use %2F for a / and %20 for a ' ' (space).)

Verification

The ZIP file downloaded is located in the directory the REST call was given. 

Restrictions & notes

  • When creating a backup, all dependencies need to be located within the folder being backed up, otherwise an error occurs.
  • Within the zip file, all JSONs must use Datameer specific endings (e.g., .imp, .dst, NOT .json).
  • If the contents of the zip file are present in the target location, the restore action will fail.
  • When restoring the contents of a zip file, the uploader becomes the OWNER of the files, with default permissions.
  • If a folder is specified by folder path but the folder doesn't exist, that folder is created and retains the user's capabilities and permissions.

Advanced parameters

Restore-Overwrite

Replaces and overwrite files that might be located within the target folder in the target system. Existing configurations with downstream dependencies cannot be overwritten.

Overwrite functions adhere to the user’s existing permission settings. If a user has the capability to overwrite Hadoop properties, they will be overwritten, otherwise not.

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/restore?overwrite'

Note

Restore-Overwrite doesn't append an existing configuration. The configuration being overwritten is deleted and the new configuration is added in its place.

Restore-Skip

If the dependencies of a file can't be resolved, the file is ignored and the REST response includes the skipped files.

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/restore?skipFilesWithMissingDependencies'

Back Up File or Folder with Permissions

Request method - GET

Description

Backup includes the data permissions for each backed up workbook file in the zip file.

URI syntax

curl -u <username>:<password> -X GET -o <name>.zip 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/backup?includeDataPermissions'

Restrictions & notes

  • Ignored if something else other than a workbook is backed up (or restored).

Back Up File or Folder with Group Permissions

Request method - GET

Description

Backup includes the group permissions for each backed up file and folder in a zip file.

URI syntax

curl -u <username>:<password> -X GET -o <name>.zip 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/backup?includeGroupPermissions'

Back Up File or Folder with File Sharing

Request method - GET

Description

Backup includes the sharing option for each backed up file and folder in the zip file. This includes permission of others and public sharing of an infographic.

URI syntax

curl -u <username>:<password> -X GET -o <name>.zip 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/backup?includeOwner'

Back Up File or Folder with Owners

Request method - GET

Description

Backup includes the owner for each backed up file and folder in the zip file.

URI syntax

curl -u <username>:<password> -X GET -o <name>.zip 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/backup?includeSharing'

Restore File or Folder Permissions

Request method - PUT

Description

Restores the permissions for a file or folder in Datameer.

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/restore?includeDataPermissions'

Restrictions & notes

  • Restores the data permissions of a workbook and restores read permissions for others.

Restore File or Folder Group Permissions

Request method - PUT

Description

Restores each file or folder with the group permissions specified in the zip file.

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/restore?includeGroupPermissions'

Advanced parameters

IgnoreUnknownGroups

Restores group permissions and skips unknown groups. 

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/restore?includeGroupPermissions&ignoreUnknownGroups'

Note

  • This option takes effect only when includeGroupPermissions or includeDataPermissions is set.
  • Unknown groups are skipped. When unknown groups are found and not set to skip, the restore operation fails.

Restore File or Folder with File Sharing

Request method - PUT

Description

Restores each file or folder with the sharing options specified in the zip file.

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/restore?includeSharing'

Restore File or Folder with Owners

Request method - PUT

Description

Restores each file or folder with the owner specified in the zip file.

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip''http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/restore?includeOwner'

Restrictions & notes

  • Restore operation is aborted if the specified owner is unknown to Datameer unless the option substituteMissingUser is passed.
  • When option substituteMissingUser is passed, unknown owners are substituted by the caller.

Advanced parameters

substituteMissingUser

Restore owners of files by substituting unknown users with the caller. 

URI syntax

curl -u <username>:<password> -X PUT --data-binary @<pathToZipFile> -H 'Content-Type: application/zip' 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<fileID>/restore?includeOwner&substituteMissingUser'

Note

  • Only takes affect when includeOwner is specified.
  • If the user specified in the backup file isn't present in the target system, the owner is set to the restoring user.