REST API Folders

Owned by Juliane Wetzel
Last updated: Apr 27, 2021
10 min read

INFO

Add the following command after the username and password to receive more meaningful HTTP errors:

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

This command can be added to each call.

INFO

Overwrite functions adhere to the user's existing permission settings.

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"

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'

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>'

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

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>'

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

INFO: 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).)

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

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

Backup-ignoreDependencies

Description

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

Description

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

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

INFO: 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).)

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
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

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).)

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'
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 X 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.

Restore-Overwrite

Description

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.

INFO

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

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'
Example Response
{
}

Restore-Skip

Description 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'

IgnoreUnknownGroups


Description

Restores group permissions and skips unknown groups. 

INFO

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.

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'

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'
Restriction & Notes

Restore operation is aborted if the specified owner is unknown to Datameer X unless the option 'substituteMissingUser' is passed.

When option 'substituteMissingUser' is passed, unknown owners are substituted by the caller.

substituteMissingUser


Description

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

INFO

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.

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'