Azure Data Lake Storage Gen2 REST API

Path Operations

This section covers the REST API operations for managing paths (files and directories) within an Azure Data Lake Storage Gen2 filesystem.

Get Properties

Retrieves the properties of a file or directory.

GET /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes

Query Parameters

Name	Description	Type	Required
`action`	Must be set to `getProperties`.	`String`	No (Implied if not specified)

Response

Returns an HTTP 200 OK status code and a JSON object containing the path's properties.

Example Response (JSON)


{
  "name": "my-directory/my-file.txt",
  "etag": "\"0x8D6E3C0E753D122\"",
  "lastModified": "2023-10-27T10:00:00Z",
  "contentLength": 1024,
  "isDirectory": false,
  "creationTime": "2023-10-27T09:55:00Z",
  "lastAccessTime": "2023-10-27T10:05:00Z",
  "owner": "msds://user/oid/guid",
  "group": "msds://group/oid/guid",
  "permissions": "rwxrwxrwx",
  "acl": "user::rwx,group::rwx,other::rwx"
}

Create Path

Creates a file or directory. If the path already exists, it may be overwritten depending on the recursive parameter.

PUT /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes
`x-ms-resource-type`	`file` or `directory`.	Yes
`x-ms-acl`	ACL entries for the new path.	No
`x-ms-owner`	Owner of the new path.	No
`x-ms-group`	Group of the new path.	No
`x-ms-permissions`	POSIX permissions.	No

Query Parameters

Name	Description	Type	Required
`recursive`	If set to `true`, creates parent directories as needed.	`Boolean`	No

Response

Returns an HTTP 201 Created status code on successful creation.

Rename Path

Renames a file or directory.

POST /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes
`x-ms-move-source`	The path to rename (relative to the filesystem root).	Yes
`x-ms-path-rename-source`	The path to rename (absolute path).	Yes
`x-ms-properties-to-copy`	Comma-separated list of properties to copy from the source to the destination (e.g., `acl,owner,group,permissions`).	No

Query Parameters

Name	Description	Type	Required
`recursive`	If set to `true`, allows renaming directories and their contents.	`Boolean`	No

Response

Returns an HTTP 201 Created status code on successful rename.

Delete Path

Deletes a file or directory.

DELETE /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes

Query Parameters

Name	Description	Type	Required
`recursive`	If set to `true`, deletes directories and their contents recursively.	`Boolean`	No

Response

Returns an HTTP 200 OK status code on successful deletion.

List Paths

Lists the paths (files and directories) within a specified directory.

GET /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes

Query Parameters

Name	Description	Type	Required
`recursive`	If set to `true`, lists all paths recursively within the specified directory.	`Boolean`	No
`maxResultsToReturn`	Specifies the maximum number of results to return.	`Integer`	No
`continuation`	A token for retrieving the next page of results.	`String`	No

Response

Returns an HTTP 200 OK status code and a JSON object containing a list of paths.

Example Response (JSON)


{
  "paths": [
    {
      "name": "my-directory/file1.txt",
      "etag": "\"0x8D6E3C0E753D122\"",
      "lastModified": "2023-10-27T10:00:00Z",
      "contentLength": 1024,
      "isDirectory": false
    },
    {
      "name": "my-directory/subdir",
      "etag": "\"0x8D6E3C0E753D123\"",
      "lastModified": "2023-10-27T09:58:00Z",
      "isDirectory": true
    }
  ],
  "continuation": "..."
}

Read Data

Reads the content of a file.

GET /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes
`Range`	Specifies a byte range to read from the file (e.g., `bytes=0-1023`).	No

Query Parameters

Name	Description	Type	Required
`action`	Must be set to `read`.	`String`	No (Implied if not specified)

Response

Returns an HTTP 200 OK status code and the file content in the response body.

Example Response (Binary/Text)


This is the content of the file.

Append Data

Appends data to an existing file.

PATCH /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes
`x-ms-append-position`	The position in the file where the data should be appended. Use `0` to append to the beginning.	Yes
`Content-Length`	The size of the data being appended.	Yes
`If-Match`	An ETag value to perform the operation only if the blob's ETag matches the specified value.	No

Request Body

The data to append to the file.

Response

Returns an HTTP 200 OK status code. The response headers contain the updated ETag and content length.

Flush Data

Flushes data to a file, committing all appended data.

POST /<filesystem_name>/<path>

Request Headers

Name	Description	Required
`x-ms-version`	Specifies the version of the Data Lake Storage Gen2 REST API.	Yes
`Authorization`	Bearer token for authentication.	Yes
`x-ms-flush-position`	The position in the file up to which data is flushed. Use the current file size to flush all data.	Yes
`If-Match`	An ETag value to perform the operation only if the blob's ETag matches the specified value.	No

Response

Returns an HTTP 200 OK status code. The response headers contain the updated ETag and content length.