Path Operations

PUT /{filesystem}/{directory|file}

Creates a file or directory in a specified filesystem.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
name String Path Yes Specifies the path of the file or directory.
resource String Query No Required for directory creation. Set to 'directory'.
recursive Boolean Query No If true, creates parent directories as needed.
Content-Length Int64 Header Yes (for files) The length of the file content in bytes.
x-ms-acl String Header No Access Control List for the path.
x-ms-owner String Header No Owner of the path.
x-ms-group String Header No Group of the path.

Request Body

Optional for directories. For files, contains the file content.

// For file creation
<file_content>

Responses

Code Description
201 Path created successfully.
404 Filesystem not found.
409 Path already exists.

HEAD /{filesystem}/{path}

Retrieves the system and user-defined properties of a path.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Path Yes Specifies the path of the file or directory.
action String Query No Set to 'getAccessControl' to retrieve ACLs.

Responses

Code Description
200 Properties retrieved successfully. Headers contain details like Content-Length, Content-Type, ETag, Last-Modified, etc.
404 Filesystem or path not found.

PATCH /{filesystem}/{path}

Sets system and user-defined properties of a path.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Path Yes Specifies the path of the file or directory.
action String Query No Set to 'setAccessControl' to modify ACLs.
x-ms-acl String Header Yes (if action=setAccessControl) The new Access Control List for the path.

Responses

Code Description
200 Properties updated successfully.
404 Filesystem or path not found.

DELETE /{filesystem}/{path}

Deletes a file or directory.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Path Yes Specifies the path of the file or directory.
recursive Boolean Query No If true and path is a directory, deletes the directory and its contents.

Responses

Code Description
200 Path deleted successfully.
404 Filesystem or path not found.
409 Path is not empty (and recursive not specified or false).

GET /{filesystem}?resource=filesystem

Lists all files and directories within a specified filesystem or directory.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Query No Specifies the directory to list. If omitted, lists the root of the filesystem.
recursive Boolean Query No If true, recursively lists all paths.
maxResults Integer Query No Maximum number of results to return.

Responses

Code Description
200 List of paths returned.
404 Filesystem not found. 
<?xml version="1.0" encoding="utf-8"?>
<Paths>
  <Path>
    <Name>dir1/file1.txt</Name>
    <IsDirectory>false</IsDirectory>
    <ETag>"0x8D9A9C9B9C9B9D9"</ETag>
    <LastModified>2023-10-27T10:00:00Z</LastModified>
    <ContentLength>1024</ContentLength>
  </Path>
  <Path>
    <Name>dir2</Name>
    <IsDirectory>true</IsDirectory>
    <ETag>"0x8D9A9C9B9C9B9D8"</ETag>
    <LastModified>2023-10-27T09:30:00Z</LastModified>
  </Path>
</Paths>

POST /{filesystem}/{sourcepath}?action=rename&destination={destinationpath}

Renames a file or directory.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
sourcepath String Path Yes The current path of the file or directory to rename.
action String Query Yes Must be set to 'rename'.
destination String Query Yes The new path for the file or directory.
recursive Boolean Query No If true and the source path is a directory, recursively renames the directory and its contents.

Responses

Code Description
200 Path renamed successfully.
404 Filesystem or source path not found.
409 Destination path already exists.

POST /{filesystem}/{path}?action=flush

Flushes the data of a file, indicating that it is complete.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Path Yes Specifies the path of the file to flush.
action String Query Yes Must be set to 'flush'.
Content-Length Int64 Header Yes The total size of the file after flushing.

Responses

Code Description
200 File flushed successfully.
404 Filesystem or path not found.
400 File is not in append mode or the specified length is incorrect.

PATCH /{filesystem}/{path}

Appends data to a file.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Path Yes Specifies the path of the file to append to.
action String Query Yes Must be set to 'append'.
position Int64 Query Yes The position in the file to append the data.
Content-Length Int64 Header Yes The size of the data being appended.

Request Body

Contains the data to be appended to the file.

<appended_data>

Responses

Code Description
200 Data appended successfully.
404 Filesystem or path not found.
400 File is not in append mode or the position is invalid.

GET /{filesystem}/{path}

Reads the content of a file.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Path Yes Specifies the path of the file to read.
offset Int64 Query No The offset in bytes to begin reading from.
count Int64 Query No The number of bytes to read.

Responses

Code Description
200 File content returned in the response body.
404 Filesystem or path not found.

GET /{filesystem}/{path}?action=getstatus

Retrieves the status of a path, including its size, owner, and permissions.

Parameters

Name Type Location Required Description
filesystem String Path Yes Specifies the name of the filesystem.
path String Path Yes Specifies the path of the file or directory.
action String Query Yes Must be set to 'getstatus'.

Responses

Code Description
200 Path status returned.
404 Filesystem or path not found. 
<?xml version="1.0" encoding="utf-8"?>
<PathStatus>
  <Path>dir1/file1.txt</Path>
  <IsDirectory>false</IsDirectory>
  <ETag>"0x8D9A9C9B9C9B9D9"</ETag>
  <LastModified>2023-10-27T10:00:00Z</LastModified>
  <ContentLength>1024</ContentLength>
  <Owner>user@example.com</Owner>
  <Group>datalakeusers</Group>
  <Permissions>rw-rw-r--</Permissions>
  <Acl>user:user@example.com:rwx,group:datalakeusers:rwx,other::-</Acl>
</PathStatus>