Directory Listing¶

Method¶

GET

Endpoint URL¶

https://xxxx.backendless.app/api/files/<path>?  
                    pattern=<pattern>&  
                    sub=<recursive>&  
                    pagesize=<pagesize>&  
                    offset=<offset>

where:

Argument	Description
`<path>`	Path of a directory to get a listing of. The path must start with the root directory identified by forward slash, for example: "`/web`".
`<pattern>`	An optional parameter. A pattern which the returned files and directories must match.
`<recursive>`	An optional parameter. A boolean value of `true` or `false`. If present and is `true`, requests that the listing must be retrieved recursively for all directories contained within .
`<pagesize>`	An optional parameter. If present, identifies how many items should be returned in the response.
`<offset>`	An optional parameter. If present, indicates the index of item in the response from which to get the `<pagesize>` items.

Request headers¶

user-token: optional value obtained as a result of the login operation.

where:

Argument Description

user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the currently logged in user will be assigned to the ownerId property of the user object which is being saved. Additionally, the operation will be executed with the security policy associated currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request Body:¶

None.

Return value¶

A collection of files and directories matching the specified pattern. The returned collection may not include all files and directories as the size of the number of returned entries is limited for paging purposes. To get the next set of file/directory entries, an additional request must be made with a different offset value. The total count of all files/directories in the listing use the Get File Count API.

Each element in the collection contains the following properties:

name - name of the file or directory without any path information
public URL - absolute URL of the file or directory
URL - relative URL of the file or directory starting from the root of the file storage
created on - a timestamp indicating when the file or directory were created

Example¶

The example below describes how to get a listing of all HTML files from the /web directory and all subdirectories.

Important

Make sure to replace xxxx in the domain name in the sample request below to the one assigned to your application.

curl "https://xxxx.backendless.app/api/files/web?pattern=*.html&sub=true"

The result of the command is the following response (the contents of the response for your application may be different):

[  
    {  
      "name": "disabled.html",  
      "createdOn": 1438338861000,  
      "publicUrl": "https:\/\/backendlessappcontent.com\/757E349F-C515-5AF3-FF5DEFF0379BFB00\/v1\/files\/web\/templates\/registration\/disabled.html",  
      "size": 1024,  
      "url": "web\/templates\/registration\/disabled.html"  
    },  
    {  
      "name": "index.html",  
      "createdOn": 1438338861000,  
      "publicUrl": "https:\/\/backendlessappcontent.com\/757E349F-C515-5AF3-FF5D-EFF0379BFB00\/v1\/files\/web\/index.html",  
      "size": 1024,  
      "url": "web\/index.html"  
    },  
    {  
      "name": "index.html",  
      "createdOn": 1439519289000,  
      "publicUrl": "https:\/\/backendlessappcontent.com\/757E349F-C515-5AF3-FF5D-EFF0379BFB00\/v1\/files\/web\/scripts\/examples\/shoppingcart\/index.html",  
      "size": 9216,  
      "url": "web\/scripts\/examples\/shoppingcart\/index.html"  
    },  
    {  
      "name": "index.html",  
      "createdOn": 1438338861000,  
      "publicUrl": "https:\/\/backendlessappcontent.com\/757E349F-C515-5AF3-FF5DEFF0379BFB00\/v1\/files\/web\/templates\/change_password\/index.html",  
      "size": 1024,  
      "url": "web\/templates\/change_password\/index.html"  
    },  
    {  
      "name": "index.html",  
      "createdOn": 1438338861000,  
      "publicUrl": "https:\/\/backendlessappcontent.com\/757E349F-C515-5AF3-FF5D-EFF0379BFB00\/v1\/files\/web\/templates\/registration\/index.html",  
      "size": 1024,  
      "url": "web\/templates\/registration\/index.html"  
    },  
    {  
      "name": "index.html",  
      "createdOn": 1438338861000,  
      "publicUrl": "https:\/\/backendlessappcontent.com\/757E349F-C515-5AF3-FF5D-EFF0379BFB00\/v1\/files\/web\/templates\/session_expiration\/index.html",  
      "size": 1024,  
      "url": "web\/templates\/session_expiration\/index.html"  
    }  
]

Errors¶

When the backend reports an error, it returns a JSON object in the following format:

{  
  "message":error-message,  
  "code":error-code  
}

The server may return the following errors:

Error Code	Error message	Notes
6000	File or directory cannot be found.	Occurs when the source file/directory cannot be found.
6006	Path contains prohibited symbols: {path name}
6007	The specified resource was not found	Occurs when the API requests to rename a non-existent file or a directory.
6029	Specified resource must be a directory	Occurs when the path to get a listing for is not a directory

Codeless Reference¶

files_api_get_directory_listing_1

where:

Argument	Description
`path`	Path of a directory to get a listing of. The path must start with the root directory identified by forward slash, for example: "`/web`".
`pattern`	An optional parameter. A pattern which the returned files and directories must match.
`include subdirectories`	An optional parameter. A boolean value of `true` or `false`. If it is `true`, requests that the listing must be retrieved recursively for all directories contained within`path`.
`page size`	An optional parameter. Identifies how many items should be returned in the response.
`page offset`	An optional parameter. Indicates the index of item in the response from which to get the `page size` items.

Returns a list containing objects representing files and folders stored in the requested directory.

Consider the following files stored in the days directory:

files_api_get_directory_listing_2

The example below retrieves a list containing all file names, as well as other related details. Files are retrieved from "days" directory.

files_api_get_directory_listing_3

The result of this operation will look as shown below after the Codeless logic runs.

files_api_get_directory_listing_4

Consider the following files stored in the misc directory.

files_api_get_directory_listing_5

The example below uses the pattern argument to retrieve only those pictures whose file extension is .jpg.

files_api_get_directory_listing_6

As you can see, the operation has retrieved a list containing file names matching the pattern argument.

files_api_get_directory_listing_7