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. Ensure you read the HTTP status codes and interpret them together with the responses.
For each call, you can add the following command:
-w"\n%{http_code}\n"After the username and password in order to receive more meaningful HTTP errors.
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 the Permissions of a Folder
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 the 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 the Others 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 the 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 the 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 the 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
This feature is available with Datameer's Advanced Governance module.
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 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/backup' > <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.
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 '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 'http://<datameerServer>:<port>/api/filesystem/folders/<folderPath>||<UUID>||<file-id>/backup?skipFilesWithMissingDependencies'
Migrate/Restore a Folder from a ZIP
This feature is available with Datameer's Advanced Governance module.
Request method - PUT
Description
Downloads 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. If the dependencies aren't in the folder, 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 system (in the target location), the restore action fails.
- 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 and the folder doesn't exist, then the folder is created regarding the users 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 can't be overwritten.
URI syntax
curl -u <username>:<password> -X PUT @<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 with the new configuration 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 @<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 '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 '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 '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 '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 also 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
- Restores operation is aborted if the specified owner is unknown to Datameer unless option
substituteMissingUseris passed. - If 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.