/v1/files/{ref}/data | Qumulo Documentation

Endpoint

/v1/files/{ref}/data

GET

Return the contents of the file as an HTTP octet stream. The etag returned by this method represents the whole state of this file. In another word, if you are reading just a portion of the data, etag could be invalid because of other changes happened to the file, even the specific portion of data you read is still intact.

Parameters

Name	Description	Required
`ref`	The file ID or the absolute path to the file system object. File IDs can be found in the id field of responses of APIs that return file attributes. You must URL-encode the paths. The APIs & Tools page in the Qumulo Core Web UI URL-encodes the paths.	Yes
`snapshot`	The snapshot ID that specifies the version of the filesystem to use. If not specified, use the head version.	No
`offset`	Read data from the requested file starting at the given 64-bit integer offset. If the offset is larger than the size of the file, the read will succeed and no data will be returned.	No
`length`	Read up to length bytes from the requested file. If the read extends beyond the end of the file, the read will return as many bytes as possible, up to length.	No

Response

Codes

Code	Description
200	Return value on success

PUT

Replace the contents of the file with the body of the request. The target file must already exist, and the content-type of the request must be application/octet-stream.

Parameters

Name	Description	Required
`ref`	The file ID or the absolute path to the file system object. File IDs can be found in the id field of responses of APIs that return file attributes. You must URL-encode the paths. The APIs & Tools page in the Qumulo Core Web UI URL-encodes the paths.	Yes
`If-Match`	ETag for expected version	No

Request

Schema

{
  "type": "object"
}

Response

Codes

Code	Description
200	Return value on success

Schema

{
  "description": "api_files_attributes",
  "type": "object",
  "properties": {
    "path": {
      "description": "Filesystem path of the object",
      "type": "string"
    },
    "name": {
      "description": "Name of this file",
      "type": "string"
    },
    "num_links": {
      "description": "How many directory entries are associated with this file",
      "type": "number"
    },
    "type": {
      "type": "string",
      "enum": [
        "FS_FILE_TYPE_FILE",
        "FS_FILE_TYPE_DIRECTORY",
        "FS_FILE_TYPE_SYMLINK",
        "FS_FILE_TYPE_UNIX_PIPE",
        "FS_FILE_TYPE_UNIX_CHARACTER_DEVICE",
        "FS_FILE_TYPE_UNIX_BLOCK_DEVICE",
        "FS_FILE_TYPE_UNIX_SOCKET"
      ],
      "description": "Resource type:\n * `FS_FILE_TYPE_DIRECTORY` - FS_FILE_TYPE_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - FS_FILE_TYPE_FILE,\n * `FS_FILE_TYPE_SYMLINK` - FS_FILE_TYPE_SYMLINK,\n * `FS_FILE_TYPE_UNIX_BLOCK_DEVICE` - FS_FILE_TYPE_UNIX_BLOCK_DEVICE,\n * `FS_FILE_TYPE_UNIX_CHARACTER_DEVICE` - FS_FILE_TYPE_UNIX_CHARACTER_DEVICE,\n * `FS_FILE_TYPE_UNIX_PIPE` - FS_FILE_TYPE_UNIX_PIPE,\n * `FS_FILE_TYPE_UNIX_SOCKET` - FS_FILE_TYPE_UNIX_SOCKET"
    },
    "major_minor_numbers": {
      "description": "The major and minor numbers for UNIX device files",
      "type": "object",
      "properties": {
        "major": {
          "description": "major",
          "type": "number"
        },
        "minor": {
          "description": "minor",
          "type": "number"
        }
      }
    },
    "symlink_target_type": {
      "type": "string",
      "enum": [
        "FS_FILE_TYPE_UNKNOWN",
        "FS_FILE_TYPE_FILE",
        "FS_FILE_TYPE_DIRECTORY"
      ],
      "description": "The type of the target file if this file is a symlink:\n * `FS_FILE_TYPE_DIRECTORY` - API_SYMLINK_TARGET_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - API_SYMLINK_TARGET_FILE,\n * `FS_FILE_TYPE_UNKNOWN` - API_SYMLINK_TARGET_UNKNOWN"
    },
    "file_number": {
      "description": "Unique ID of this file",
      "type": "string"
    },
    "id": {
      "description": "Unique ID of this file",
      "type": "string"
    },
    "mode": {
      "description": "POSIX-style file mode (octal)",
      "type": "string"
    },
    "owner": {
      "description": "File owner",
      "type": "string"
    },
    "owner_details": {
      "description": "File owner details",
      "type": "object",
      "properties": {
        "id_type": {
          "type": "string",
          "enum": [
            "LOCAL_USER",
            "LOCAL_GROUP",
            "NFS_GID",
            "NFS_UID",
            "SMB_SID",
            "INTERNAL",
            "QUMULO_OPERATOR"
          ],
          "description": "id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `SMB_SID` - SMB_SID"
        },
        "id_value": {
          "description": "id_value",
          "type": "string"
        }
      }
    },
    "group": {
      "description": "File group",
      "type": "string"
    },
    "group_details": {
      "description": "File group details",
      "type": "object",
      "properties": {
        "id_type": {
          "type": "string",
          "enum": [
            "LOCAL_USER",
            "LOCAL_GROUP",
            "NFS_GID",
            "NFS_UID",
            "SMB_SID",
            "INTERNAL",
            "QUMULO_OPERATOR"
          ],
          "description": "id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `SMB_SID` - SMB_SID"
        },
        "id_value": {
          "description": "id_value",
          "type": "string"
        }
      }
    },
    "blocks": {
      "description": "Number of blocks used by the file",
      "type": "string"
    },
    "datablocks": {
      "description": "Number of data blocks used by the file",
      "type": "string"
    },
    "metablocks": {
      "description": "Number of meta blocks used by the file",
      "type": "string"
    },
    "size": {
      "description": "File size in bytes",
      "type": "string"
    },
    "access_time": {
      "description": "Last time content was read, RFC 3339 format",
      "type": "string"
    },
    "modification_time": {
      "description": "Last time content was modified, RFC 3339 format",
      "type": "string"
    },
    "change_time": {
      "description": "Last time content or attributes were modified, RFC 3339 format",
      "type": "string"
    },
    "creation_time": {
      "description": "File creation time, RFC 3339 format",
      "type": "string"
    },
    "child_count": {
      "description": "Count of children (valid for directories)",
      "type": "number"
    },
    "extended_attributes": {
      "description": "SMB extended file attributes",
      "type": "object",
      "properties": {
        "read_only": {
          "description": "read_only",
          "type": "boolean"
        },
        "hidden": {
          "description": "hidden",
          "type": "boolean"
        },
        "system": {
          "description": "system",
          "type": "boolean"
        },
        "archive": {
          "description": "archive",
          "type": "boolean"
        },
        "temporary": {
          "description": "temporary",
          "type": "boolean"
        },
        "compressed": {
          "description": "compressed",
          "type": "boolean"
        },
        "not_content_indexed": {
          "description": "not_content_indexed",
          "type": "boolean"
        },
        "sparse_file": {
          "description": "sparse_file",
          "type": "boolean"
        },
        "offline": {
          "description": "offline",
          "type": "boolean"
        }
      }
    },
    "directory_entry_hash_policy": {
      "type": "string",
      "enum": [
        "FS_DIRECTORY_HASH_VERSION_LOWER",
        "FS_DIRECTORY_HASH_VERSION_FOLDED"
      ],
      "description": "Hash policy for directory entries:\n * `FS_DIRECTORY_HASH_VERSION_FOLDED` - FS_DIRECTORY_HASH_VERSION_FOLDED,\n * `FS_DIRECTORY_HASH_VERSION_LOWER` - FS_DIRECTORY_HASH_VERSION_LOWER"
    },
    "data_revision": {
      "description": "The revision for changes to the underlying file data.",
      "type": "string"
    },
    "user_metadata_revision": {
      "description": "The revision for changes to the user defined metadata of the file.",
      "type": "string"
    }
  }
}

PATCH

Set the contents of the file, at the given offset, to the body of the request. The target file must already exist, and the Content-Type of the request must be application/octet-stream.

Parameters

Name	Description	Required
`ref`	The file ID or the absolute path to the file system object. File IDs can be found in the id field of responses of APIs that return file attributes. You must URL-encode the paths. The APIs & Tools page in the Qumulo Core Web UI URL-encodes the paths.	Yes
`offset`	Write the provided data at the given 64-bit integer offset. If the offset is greater than the size of the file, the file will be zero-extended up to offset before the data is written. (default: 0)	No
`If-Match`	ETag for expected version	No

Request

Schema

{
  "type": "object"
}

Response

Codes

Code	Description
200	Return value on success

Schema

{
  "description": "api_files_attributes",
  "type": "object",
  "properties": {
    "path": {
      "description": "Filesystem path of the object",
      "type": "string"
    },
    "name": {
      "description": "Name of this file",
      "type": "string"
    },
    "num_links": {
      "description": "How many directory entries are associated with this file",
      "type": "number"
    },
    "type": {
      "type": "string",
      "enum": [
        "FS_FILE_TYPE_FILE",
        "FS_FILE_TYPE_DIRECTORY",
        "FS_FILE_TYPE_SYMLINK",
        "FS_FILE_TYPE_UNIX_PIPE",
        "FS_FILE_TYPE_UNIX_CHARACTER_DEVICE",
        "FS_FILE_TYPE_UNIX_BLOCK_DEVICE",
        "FS_FILE_TYPE_UNIX_SOCKET"
      ],
      "description": "Resource type:\n * `FS_FILE_TYPE_DIRECTORY` - FS_FILE_TYPE_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - FS_FILE_TYPE_FILE,\n * `FS_FILE_TYPE_SYMLINK` - FS_FILE_TYPE_SYMLINK,\n * `FS_FILE_TYPE_UNIX_BLOCK_DEVICE` - FS_FILE_TYPE_UNIX_BLOCK_DEVICE,\n * `FS_FILE_TYPE_UNIX_CHARACTER_DEVICE` - FS_FILE_TYPE_UNIX_CHARACTER_DEVICE,\n * `FS_FILE_TYPE_UNIX_PIPE` - FS_FILE_TYPE_UNIX_PIPE,\n * `FS_FILE_TYPE_UNIX_SOCKET` - FS_FILE_TYPE_UNIX_SOCKET"
    },
    "major_minor_numbers": {
      "description": "The major and minor numbers for UNIX device files",
      "type": "object",
      "properties": {
        "major": {
          "description": "major",
          "type": "number"
        },
        "minor": {
          "description": "minor",
          "type": "number"
        }
      }
    },
    "symlink_target_type": {
      "type": "string",
      "enum": [
        "FS_FILE_TYPE_UNKNOWN",
        "FS_FILE_TYPE_FILE",
        "FS_FILE_TYPE_DIRECTORY"
      ],
      "description": "The type of the target file if this file is a symlink:\n * `FS_FILE_TYPE_DIRECTORY` - API_SYMLINK_TARGET_DIRECTORY,\n * `FS_FILE_TYPE_FILE` - API_SYMLINK_TARGET_FILE,\n * `FS_FILE_TYPE_UNKNOWN` - API_SYMLINK_TARGET_UNKNOWN"
    },
    "file_number": {
      "description": "Unique ID of this file",
      "type": "string"
    },
    "id": {
      "description": "Unique ID of this file",
      "type": "string"
    },
    "mode": {
      "description": "POSIX-style file mode (octal)",
      "type": "string"
    },
    "owner": {
      "description": "File owner",
      "type": "string"
    },
    "owner_details": {
      "description": "File owner details",
      "type": "object",
      "properties": {
        "id_type": {
          "type": "string",
          "enum": [
            "LOCAL_USER",
            "LOCAL_GROUP",
            "NFS_GID",
            "NFS_UID",
            "SMB_SID",
            "INTERNAL",
            "QUMULO_OPERATOR"
          ],
          "description": "id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `SMB_SID` - SMB_SID"
        },
        "id_value": {
          "description": "id_value",
          "type": "string"
        }
      }
    },
    "group": {
      "description": "File group",
      "type": "string"
    },
    "group_details": {
      "description": "File group details",
      "type": "object",
      "properties": {
        "id_type": {
          "type": "string",
          "enum": [
            "LOCAL_USER",
            "LOCAL_GROUP",
            "NFS_GID",
            "NFS_UID",
            "SMB_SID",
            "INTERNAL",
            "QUMULO_OPERATOR"
          ],
          "description": "id_type:\n * `INTERNAL` - INTERNAL,\n * `LOCAL_GROUP` - LOCAL_GROUP,\n * `LOCAL_USER` - LOCAL_USER,\n * `NFS_GID` - NFS_GID,\n * `NFS_UID` - NFS_UID,\n * `QUMULO_OPERATOR` - QUMULO_OPERATOR,\n * `SMB_SID` - SMB_SID"
        },
        "id_value": {
          "description": "id_value",
          "type": "string"
        }
      }
    },
    "blocks": {
      "description": "Number of blocks used by the file",
      "type": "string"
    },
    "datablocks": {
      "description": "Number of data blocks used by the file",
      "type": "string"
    },
    "metablocks": {
      "description": "Number of meta blocks used by the file",
      "type": "string"
    },
    "size": {
      "description": "File size in bytes",
      "type": "string"
    },
    "access_time": {
      "description": "Last time content was read, RFC 3339 format",
      "type": "string"
    },
    "modification_time": {
      "description": "Last time content was modified, RFC 3339 format",
      "type": "string"
    },
    "change_time": {
      "description": "Last time content or attributes were modified, RFC 3339 format",
      "type": "string"
    },
    "creation_time": {
      "description": "File creation time, RFC 3339 format",
      "type": "string"
    },
    "child_count": {
      "description": "Count of children (valid for directories)",
      "type": "number"
    },
    "extended_attributes": {
      "description": "SMB extended file attributes",
      "type": "object",
      "properties": {
        "read_only": {
          "description": "read_only",
          "type": "boolean"
        },
        "hidden": {
          "description": "hidden",
          "type": "boolean"
        },
        "system": {
          "description": "system",
          "type": "boolean"
        },
        "archive": {
          "description": "archive",
          "type": "boolean"
        },
        "temporary": {
          "description": "temporary",
          "type": "boolean"
        },
        "compressed": {
          "description": "compressed",
          "type": "boolean"
        },
        "not_content_indexed": {
          "description": "not_content_indexed",
          "type": "boolean"
        },
        "sparse_file": {
          "description": "sparse_file",
          "type": "boolean"
        },
        "offline": {
          "description": "offline",
          "type": "boolean"
        }
      }
    },
    "directory_entry_hash_policy": {
      "type": "string",
      "enum": [
        "FS_DIRECTORY_HASH_VERSION_LOWER",
        "FS_DIRECTORY_HASH_VERSION_FOLDED"
      ],
      "description": "Hash policy for directory entries:\n * `FS_DIRECTORY_HASH_VERSION_FOLDED` - FS_DIRECTORY_HASH_VERSION_FOLDED,\n * `FS_DIRECTORY_HASH_VERSION_LOWER` - FS_DIRECTORY_HASH_VERSION_LOWER"
    },
    "data_revision": {
      "description": "The revision for changes to the underlying file data.",
      "type": "string"
    },
    "user_metadata_revision": {
      "description": "The revision for changes to the user defined metadata of the file.",
      "type": "string"
    }
  }
}