Documentation deprecated: This documentation is no longer being updated as of 3.8.0. For up-to-date information, see the guide information in the IBM Developer Community and the endpoint reference in IBM API Explorer.

/files/browse

View the metadata of the specified directory and its contents, which can be filtered and sorted.

To browse by using bearer token authentication and file IDs, or to browse content in cloud storage, use the /files endpoint.

Requirements
  • Available as of Enterprise Server version 3.6.0.
  • Browse requests can timeout if the path includes a large directory tree with many files or if the server is slow. The default timeout is 10 seconds. To increase the timeout:
    1. Change the default timeout by running the following command (this example increases the timeout to 5 minutes):
      asconfigurator -x "set_server_data;max_response_time_sec,300"
    2. Restart asperanoded to activate the update.
      # service asperanoded restart
Access Control
  • HTTP Basic Auth
    Users who authenticate with Node API credentials can browse paths that are within their docroot. Access key users can browse paths that are within the path set in the access key.
URL
POST https://{domain}:9092/files/browse

Sample Request
curl -i -u user:secret -X POST https://{domain}:9092/files/browse \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d @request_body.json

Where request_body.json contains the following:
{
    "path" : "/full/path",
    "skip" : 100,
    "count" : 100,
    "sort" : "path",
    "case_sensitive" : false,
    "filters" : {
         "types" : ["file", "directory", ... ],
         "paths" : ["/a/*", "b/*/c*"],
         "basenames" : ["*.jpg", "*.gif"],
         "size_min" : 1000,
         "size_max" : 10000,
         "mtime_min" : "2011-01-01 00:00:00",
         "mtime_max" : "2011-01-31 11:59:59",
  }
}
Headers
Header Name Required Description Values
Content-Type Optional The format of the request data. application/json
Accept Optional The format of the response data. application/json

Request Body
Element Required Type Description
path Required String Absolute path to file or directory.
skip Optional Unsigned integer Skip the first "skip" results. Default 0
count Optional Unsigned integer Return no more than "count" results.  It is the client’s responsibility to keep track of number of results returned. Default 100.
sort Optional String Result sorting policy. Values:
  • path
  • type (directory/file)
  • size_a (bytes, ascending)
  • size_d (bytes, descending)
  • mtime_a (modification date, ascending)
  • mtime_d (modification date, descending)
case_sensitive Optional Boolean Specify if sort and basename are case sensitive (true) or not (false). Default: false. Available as of version 3.7.1.
filters Optional JSON Array of filters to apply to the results.
types Optional String Return data only for the specified content types: file, symbolic_link, or directory.
paths Optional String Return data only for path names that match the specified path.
basenames Optional String Return data only for files with basenames that match the specified basenames.
size_min Optional Unsigned integer Include files that are greater than or equal to size_min (in bytes). NOTE: This setting automatically restricts the results to files, equivalent to setting "types":"file".
size_max Optional Unsigned integer Include files that are less than size_max (in bytes). NOTE: This setting automatically restricts the results to files, equivalent to setting "types":"file".
mtime_min Optional String Include files that were updated after mtime_min, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
mtime_max Optional String Include files that were updated before mtime_max, in the format "2011-01-31T12:59:59Z", T or space in the middle; Z optional at the end.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
    "self" : {
    "path" : "/Users/aspera/Documents",
    "basename" : "Documents",
    "type" : "directory",
    "size" : 0,
    "mtime" : "2018-02-26T22:49:43Z",
    "permissions" : [
        { "name" : "view" },
        { "name" : "edit" },
        { "name" : "delete" }
        ]
    },
    "items" : [
        {
            "path" : "/Users/aspera/Documents/test_folder_new",
            "basename" : "test_folder_new",
            "type" : "directory",
            "size" : 0,
            "mtime" : "2018-02-19T17:43:59Z",
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ]
        },
        {
            "path" : "/Users/aspera/Documents/sample.txt",
            "basename" : "sample.txt",
            "type" : "file",
            "size" : 445,
            "mtime" : "2018-02-09T23:08:46Z",
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ],
            "filelock" : null
        },
        {
            "path" : "/Users/aspera/Documents/sample.partial",
            "basename" : "sample.partial",
            "type" : "file",
            "size" : 445,
            "mtime" : "2018-02-09T23:08:46Z",
            "partial_file" : true,
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ],
            "filelock" : null
        },
        {
            "path" : "/Users/aspera/Documents/symlink1",
            "basename" : "symlink1",
            "type" : "symbolic_link",
            "size" : 34,
            "mtime" : "2018-02-26T22:48:02Z",
            "permissions" : [
                { "name" : "view" },
                { "name" : "edit" },
                { "name" : "delete" }
            ],
            "target" : {
                "path" : "/Users/aspera/Documents/sample.txt",
                "basename" : "sample.txt",
                "type" : "file",
                "size" : 445,
                "mtime" : "2018-02-09T23:08:46Z",    
                "permissions" : [
                    { "name" : "view" },
                    { "name" : "edit" },
                    { "name" : "delete" }
                ]
            },
            "filelock" : null
        }
    ],
    "item_count" : 4,
    "total_count" : 4,
    "parameters" : {
        "path" : "/Users/aspera/Documents",
        "skip" : 0,
        "count" : 100
    }
}

Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request contains a formatting or syntax error.
500 Internal Server Error Error The server configuration is invalid.
Response
Element Type Description
self JSON JSON object that contains the metadata associated with the base path of the request.
path String The pathname of the file, directory, or symbolic link.
basename String The base name of the path.
type String The type of the path. Value can be file, directory, or symbolic_link.
size Unsigned integer The size of the file, directory, or symbolic link, in bytes.
mtime String The item's modification time, in ISO format.
partial_file Boolean Returned if the file is a partial file.
permissions JSON JSON array of the user's permissions on the item.
name String The permission. Value can be view, edit, and delete.
target JSON JSON object that contains the metadata for the target of a symbolic link.
filelock String The filelock status of the file. Only returned for files.
items JSON JSON object that contains the metadata for the files, directories, and symbolic links that match the filtering specifications.
item_count Unsigned integer The number of items returned by the request, calculated as the total number of items in the path minus the number of items that are skipped and filtered.
total_count Unsigned integer The total number of items in the request path, minus the number of items that are filtered.
parameters JSON JSON object that contains the parameters of the request.
path String The path that was browsed.
skip Unsigned integer The number of items to skip in the result.
count Unsigned integer The maximum number of items that are returned in the response
Video player

Video

×