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. 
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
includeGroupPermissionsorincludeDataPermissionsis 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
substituteMissingUseris passed. - When option
substituteMissingUseris 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
includeOwneris specified. - If the user specified in the backup file isn't present in the target system, the owner is set to the restoring user.