Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Version:

Onezone REST API Oneprovider REST API Onepanel REST API

Version:

List directory files and subdirectories

GET /data/{id}/children

Returns the list of directory files and subdirectories for directory specified by $DIR_ID.

NOTE: the listing may contain files that are not fully synchronized or have been deleted in parallel. For that reason, it's recommended to safeguard consecutive calls referring to the directory children against ENOENT errors.

NOTE: since version 21.02.5, this endpoint accepts options as JSON body rather than in the query string. Moreover, some of the attributes have been renamed and the list of available ones has been extended. The old behaviour of the endpoint has been retained but is DEPRECATED and scheduled for deletion in the future major release. The following changes in attribute names were introduced:

file_id -> fileId
mode -> posixPermissions
parent_id -> parentFileId
storage_group_id -> displayGid
storage_user_id -> displayUid
is_fully_replicated -> isFullyReplicatedLocally
provider_id -> originProviderId
shares -> directShareIds
owner_id -> ownerUserId
hardlinks_count -> hardlinkCount

Example cURL requests

Get files in space subdirectory

curl -H "X-Auth-Token: $TOKEN" -H 'Content-type: application/json' \
-X GET "https://$PROVIDER_HOST/api/v3/oneprovider/data/$DIR_ID/children" -d '{
  "attributes": ["name", "size", "xattr.key"],
  "limit": 2
}'

{
    "children": [
        { 
            "name": File1.txt,
            "size": 1024,
            "xattr.key": "extended_attribute_value"
        },
        { 
            "name": File2.txt,
            "size": 16384,
            "xattr.key": null
        }
    ],
    "isLast": false,
    "nextPageToken": "g2gDZAAKbGlua190b2tlbmgCZAAMY2FjaGVkX3Rva2VuWgADY..."
}

Path parameters

Parameter	Type & Description
id required	string Id of the directory to be listed.

Query parameters

Parameter	Type & Description
legacy_options	string The old behaviour of the endpoint has been retained but is DEPRECATED and scheduled for deletion in the future major release. You may refer to the docs for 21.02.4, but it's recommended to use the new API with options as JSON body.

Request body

application/json

Property	Type & Description
limit integer Specifies the maximum number of entries that can be returned in one result batch. If there are more files, they can be retrieved using options that specify a custom starting point (`token`, `index`).
token string Determines the starting point for listing. The listing will start from the next page (batch) of entries which follows the page previously obtained along with the corresponding `nextPageToken`. Cannot be provided alongside the `index` or `tuneForLargeContinuousListing` parameters.
index string Determines the starting point for listing. The listing will (inclusively) start from the first file whose name is lexicographically greater or equal to the specified index. Cannot be provided alongside the `token` parameter.
offset integer Expressed in number of entries, further adjusts the starting point of listing indicated by the `index` parameter (or the list beginning if the `index` is not specified). The value can be negative, in such case entries preceding the starting point will be returned. Cannot be provided alongside the `token` parameter.
tuneForLargeContinuousListing boolean This option increases performance of listing large directories (with thousands of files) when using subsequent calls with paging tokens. CAUTION!! When enabled, there is no guarantee that changes in the file tree performed after the start of listing will be included. Therefore it shouldn't be used when the listing result is expected to be up to date with the state of the file tree at the moment of listing. It should be avoided if the interval between subsequent listings is longer than 10 seconds, otherwise the listing performance will be much worse. Overusing this option may cause a significant load on the Oneprovider. Cannot be provided alongside the `token` parameter.
attributes array of strings List of names of the attributes to be included in the result. For a shared file/directory accessed in public mode, only the following attributes are available: `fileId`, `index`, `type`, `activePermissionsType`, `mode`, `name`, `conflictingName`, `parentFileId`, `creationTime`, `atime`, `mtime`, `ctime`, `size`, `directShareIds`, `symlinkValue`, `hasCustomMetadata`, `hasJsonMetadata`, `jsonMetadata`, `xattr.*`. If not provided, by default all attributes are returned.

Request Examples

Shell

oneprovider-rest-cli listChildren id=$FILE_ID limit=100 index=filename.txt

Responses

application/json

200

The list of directory files and subdirectories.

Property Type & Description

children

array of objects (FileAttributes)

The list of directory files and subdirectories.

fileId

string

Id of the file/directory. Successor of the deprecated file_id.

index

string

Index pointing to this file/directory that can be provided as a starting point when listing files.

type

string (FileType)

The type of the file:

REG - regular file,
DIR - directory,
SYMLNK - symbolic link.

Enum:

REGDIRSYMLNK

activePermissionsType

string

Type of permissions that are taken into account when determining access rights to this file/directory.

Enum:

posixacl

posixPermissions

string

POSIX file permissions as string expressing octal notation. For a shared file/directory accessed in public mode, only the last byte (other) is shown, as it applies to the anonymous users accessing it. Successor of the deprecated mode.

acl

array of objects (Ace)

An ACL (Access Control List) is an ordered list of ACEs (Access Control Entries).

aceType string Enum: ALLOWDENY
identifier string
aceFlags integer
acemask integer

name

string

Name of the file/directory. In case of name conflicts (when two files with identical names are created simultaneously in two providers), this name is disambiguated by extending it with originProviderId.

conflictingName

string

The original name of the file/directory in case of file name conflict, as described in name. null if there is no file name conflict.

path

string

Logical path to the file/directory.

parentFileId

string

Id of the parent directory or null in case of file tree root (space root, archives root, trash, root of a shared file/directory). Successor of the deprecated parent_id.

displayGid

integer

GID of this file/directory displayed in the Oneclient's mounted filesystem. Successor of the deprecated storage_group_id.

displayUid

integer

UID of this file/directory displayed in the Oneclient's mounted filesystem. Successor of the deprecated storage_user_id.

creationTime

integer

Item's creation timestamp (UNIX epoch, in seconds). NOTE: in case of items imported from storage or created in Oneproviders in version 21.02.5 or lower it is assumed as minimum of atime, mtime and ctime.

atime

integer

Last time an item was accessed. (UNIX epoch, in seconds).

mtime

integer

Last time the item's content was modified. For regular files, indicates the time of the last write or truncate operation on the file. For directories, updated when a child item is added, renamed or deleted. (UNIX epoch, in seconds).

ctime

integer

Last time the item's metadata was changed, e.g. permissions. It' s also always updated when the modification time changes. (UNIX epoch, in seconds).

size

integer

The logical size of the file/directory in bytes. For directories, it can be null when directory statistics are not enabled or not yet calculated. See directory size statistics for more information and details about different data size metrics.

isFullyReplicatedLocally

boolean

Indicates whether a complete file replica is present on the queried provider. Applicable only for regular files (null otherwise).

localReplicationRate

number

Ratio (0.0 .. 1.0) of the local replica size present on the queried provider to the total logical data size. See also directory size statistics for more information about different data size metrics.

originProviderId

string

Id of the provider in which this file/directory was created.

directShareIds

array of strings

The list of Ids of shares created for this file/directory. For every share, only the root file/directory will contain the share Id on the list and nested files/directories won't. For a shared file/directory accessed in public mode, shows only the Id of the share in the context of which the file is being accessed. Successor of the deprecated shares.

ownerUserId

string

User Id of the owner of this file/directory. Successor of the deprecated owner_id.

hardlinkCount

integer

The number of hard links (including this one) associated with this file/directory.

symlinkValue

string

The path to which the symbolic link points. Applicable only for symlinks (null otherwise). NOTE: The path is shown even for a shared file/directory accessed in public mode.

effProtectionFlags

any

effDatasetProtectionFlags

any

effDatasetInheritancePath

any

effQosInheritancePath

any

aggregateQosStatus

any (AggregateQosStatus)

archiveRecallRootFileId

string

Id of the archive recall that this file/directory belongs to (is in the subtree of). Archive recall is a process that creates a copy of a dataset archive (snapshot) in the space filesystem, i.e. creates a regular directory, but the files and directories inside are assigned this attribute. null when the file does not belong to any archive recall.

hasCustomMetadata

boolean

Indicates whether this file/directory has any custom metadata attached (xattr, JSON or RDF).

hasJsonMetadata

boolean

Indicates whether this file/directory has any JSON custom metadata attached.

jsonMetadata

object

JSON metadata associated with the file. Special cases:

jsonMetadata==null and hasJsonMetadata==true - the JSON metadata is set and equal to null (which is a valid JSON itself).
jsonMetadata==null and hasJsonMetadata==false - there is no JSON metadata at all.

xattr.*

string

Value of requested extended attribute key (* is replaced with the key). Repeated for each requested key. null when given extended attribute was not found.

isLast

boolean (IsLast)

Due to delays in synchronization between Oneproviders, the number of returned entries can be smaller than the requested limit, even though there are still some ensuing ones. The isLast flag is the only valid indicator that all entries has been listed.

nextPageToken

string (ListPageToken)

A token in the listing response that can be passed in the consecutive request to start listing from the next page of entries. When end of list is reached, the token is returned with a null value.

Example

application/json

{
  "children": [
    {
      "fileId": "00000CF4706775696423745F772D67686431633765446F4D76546D6...",
      "index": "g2gDZAAKbGlzdF9pbmRleG0AAAAEbmFtZW0AAAAHdHJlZV9pZA",
      "type": "REG",
      "activePermissionsType": "posix",
      "posixPermissions": "511",
      "acl": [],
      "name": "File1.txt@a47b8b7a04b197c6cd99581047b8b7ad",
      "conflictingName": "File1.txt",
      "path": "/space/Dir1/File1.txt",
      "parentFileId": "000006CB66373686172654775696423333964323636616564636562...",
      "displayGid": 1101841,
      "displayUid": 1935313,
      "atime": 1464958683054,
      "mtime": 1464958683051,
      "ctime": 1464958681054,
      "size": 1024,
      "isFullyReplicatedLocally": false,
      "localReplicationRate": 0.8,
      "originProviderId": "a47b8b7a04b197c6cd99581047b8b7ad",
      "directShareIds": [
        "1d24c36707d99197c6cd995810a43aca",
        "6825604b0eb6a47b8b7a04b6369eb24d"
      ],
      "ownerUserId": "b6b6a47b8b7a04b63a45604b07b8b7a2",
      "hardlinkCount": 1,
      "symlinkValue": null,
      "hasCustomMetadata": true,
      "effProtectionFlags": [
        "data_protection",
        "metadata_protection"
      ],
      "effDatasetProtectionFlags": [
        "data_protection"
      ],
      "effDatasetInheritancePath": "direct_and_ancestor",
      "effQosInheritancePath": "ancestor",
      "aggregateQosStatus": "fulfilled",
      "archiveRecallRootFileId": "000006431633765446F4D76546D6F47067D67686431633765446F4D76546D6....",
      "xattr.key1": "value1",
      "xattr.key2": null
    }
  ],
  "isLast": false,
  "nextPageToken": "g2gDZAAKbGlua190b2tlbmgCZAAMY2FjaGVkX3Rva2VuWgADY..."
}

400

Invalid request.

Property

Type & Description

error

object (ErrorJson)

Object describing an error.

id required

string

String identifying the error type. Does not change between error instances.

description required

string

Human readable error description. May contain information specific to given error instance.

details

object

Details about the error instance. The object schema is specific to each error type.

ctx required

object (ErrorJsonCtx)

Technical information about error.

timestamp required integer Timestamp in milliseconds.
serviceReleaseVersion required string Release version of a product, for example "25.0".
serviceId required string Identifier of a service instance — either Oneprovider Id or "onezone".
serviceDomain required string Domain of the service.
serviceBuildVersion required string Build version of the service.
service required string Short name of service. Enum: ozwopwozpopp
onedataErrorsRevision required string Revision of onedata-errors repo, where the error is defined.
module required string Module where the error occurred.
line required integer Line number in the module where the error occurred.

Example

application/json

{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}

403

Forbidden request.

Property

Type & Description

error

object (ErrorJson)

Object describing an error.

id required

string

String identifying the error type. Does not change between error instances.

description required

string

Human readable error description. May contain information specific to given error instance.

details

object

Details about the error instance. The object schema is specific to each error type.

ctx required

object (ErrorJsonCtx)

Technical information about error.

timestamp required integer Timestamp in milliseconds.
serviceReleaseVersion required string Release version of a product, for example "25.0".
serviceId required string Identifier of a service instance — either Oneprovider Id or "onezone".
serviceDomain required string Domain of the service.
serviceBuildVersion required string Build version of the service.
service required string Short name of service. Enum: ozwopwozpopp
onedataErrorsRevision required string Revision of onedata-errors repo, where the error is defined.
module required string Module where the error occurred.
line required integer Line number in the module where the error occurred.

Example

application/json

{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}

404

Invalid path - file or directory not found.

Property

Type & Description

error

object (ErrorJson)

Object describing an error.

id required

string

String identifying the error type. Does not change between error instances.

description required

string

Human readable error description. May contain information specific to given error instance.

details

object

Details about the error instance. The object schema is specific to each error type.

ctx required

object (ErrorJsonCtx)

Technical information about error.

timestamp required integer Timestamp in milliseconds.
serviceReleaseVersion required string Release version of a product, for example "25.0".
serviceId required string Identifier of a service instance — either Oneprovider Id or "onezone".
serviceDomain required string Domain of the service.
serviceBuildVersion required string Build version of the service.
service required string Short name of service. Enum: ozwopwozpopp
onedataErrorsRevision required string Revision of onedata-errors repo, where the error is defined.
module required string Module where the error occurred.
line required integer Line number in the module where the error occurred.

Example

application/json

{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}

500

Internal server error.

Property

Type & Description

error

object (ErrorJson)

Object describing an error.

id required

string

String identifying the error type. Does not change between error instances.

description required

string

Human readable error description. May contain information specific to given error instance.

details

object

Details about the error instance. The object schema is specific to each error type.

ctx required

object (ErrorJsonCtx)

Technical information about error.

timestamp required integer Timestamp in milliseconds.
serviceReleaseVersion required string Release version of a product, for example "25.0".
serviceId required string Identifier of a service instance — either Oneprovider Id or "onezone".
serviceDomain required string Domain of the service.
serviceBuildVersion required string Build version of the service.
service required string Short name of service. Enum: ozwopwozpopp
onedataErrorsRevision required string Revision of onedata-errors repo, where the error is defined.
module required string Module where the error occurred.
line required integer Line number in the module where the error occurred.

Example

application/json

{
  "error": {
    "id": "example",
    "description": "This is an example error.",
    "ctx": {
      "timestamp": 1750762637248,
      "serviceReleaseVersion": "25.0",
      "serviceId": "a7ee2722915b8bf7fb064eb65087cc61ch9357",
      "serviceDomain": "dev-oneprovider-krakow.default.svc.cluster.local",
      "serviceBuildVersion": "231-g8d26f953c3",
      "service": "opw",
      "onedataErrorsRevision": "ca3af8cb",
      "module": "metadata_req",
      "line": 45
    }
  }
}