Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Onezone REST API Oneprovider REST API Onepanel REST API

Subscribe to file events

POST /changes/metadata/{sid}

This method subscribes through HTTP streaming on events of specific type for a given space.

Until the connection is kept alive, the events will be streamed to subscribers as soon as they are occur. The optional timeout parameter can be used to automatically disconnect when no events occur in a given time window.

This operation requires space_view_changes_stream privilege.

Example cURL requests

Listen to space change events

curl -N -H "X-Auth-Token: $TOKEN" \
-X POST "https://$PROVIDER_HOST/api/v3/oneprovider/changes/metadata/$SPACE_ID" \
-H "Content-Type: application/json" -d "@./changes_req.json"

Path parameters

Parameter Type & Description
sid required
string

Space Id.

Query parameters

Parameter Type & Description
timeout
integer

Optional timeout in milliseconds, which allows to automatically break connection when no event occured in specified time. By default the timeout is unlimited.
last_seq
integer

Last known file metadata sequence number

Request body

application/json

Specification of metadata changes to observe.

PropertyType & Description
triggers
array of strings

List of documents which modifications should trigger sending changes.

fileMeta
object

Specification of fileMeta fields to observe.

always
boolean

Indicates whether specified fileMeta fields should be sent on other metadata changes.

fields
array of strings
fileLocation
object

Specification of fileLocation fields to observe.

always
boolean

Indicates whether specified fileLocation fields should be sent on other metadata changes.

fields
array of strings
times
object

Specification of times fields to observe.

always
boolean

Indicates whether specified times fields should be sent on other metadata changes.

fields
array of strings
customMetadata
object

Specification of customMetadata fields to observe.

always
boolean

Indicates whether specified customMetadata fields should be sent on other metadata changes.

fields
array of strings

Extended attribute names to retrieve. In case of missing fields null values are returned. In order to fetch special attributes additional keys can be specified, namely onedata_json, onedata_rdf or onedata_keyvalue (fetches all fields beside special ones).

exists
array of strings

Extended attribute names to check for existence. Existence of special attributes can also be checked by specifying onedata_json, onedata_rdf or onedata_keyvalue (checks if any normal attribute exists).

Request Examples

Shell
cat changes_req.json | oneprovider-rest-cli streamSpaceChanges sid=$SPACE_ID timeout=10000 last_seq=124721 -

Responses

application/json
200

Subscription to events has been successful.

PropertyType & Description
fileId
string

Unique Id of the file.

filePath
string

Absolute path to the file (starting with the Space name).

seq
string

Sequence number (version) of the metadata document.

fileMeta
object

Requested fileMeta fields and additional information.

rev
string

Last revision of fileMeta.

mutators
array of strings
deleted
boolean

Indicates whether this metadata was deleted or not.

changed
boolean

Indicates whether changes occured to this metadata or not.

fields
object
name
string

File name.

type
string (FileType)

The type of the file:

  • REG - regular file,
  • DIR - directory,
  • SYMLNK - symbolic link.
Enum:
REGDIRSYMLNK
mode
integer

POSIX file permissions.

owner
string

File owner.

provider_id
string

Id of provider which created this file.

shares
array of strings

Array of this file shares Ids.

deleted
boolean

Set to 'true' when file itself was deleted but file metadata must remain for some time. Otherwise false.

fileLocation
object

Requested fileLocation fields and additional information.

rev
string

Last revision of fileLocation.

mutators
array of strings
deleted
boolean

Indicates whether this metadata was deleted or not.

changed
boolean

Indicates whether changes occured to this metadata or not.

fields
object
provider_id
string

Provider Id in which change occured.

storage_id
string

Storage Id in which file exists.

size
integer

File size.

space_id
string

Space Id in which space exists.

storage_file_created
boolean

Indicates whether file was created on storage or only metadata exists.

times
object

Requested times fields and additional information.

rev
string

Last revision of times.

mutators
array of strings
deleted
boolean

Indicates whether this metadata was deleted or not.

changed
boolean

Indicates whether changes occured to this metadata or not.

fields
object
atime
integer

POSIX atime.

mtime
integer

POSIX mtime.

ctime
integer

POSIX ctime.

customMetadata
object

Requested customMetadata fields and additional information.

rev
string

Last revision of customMetadata.

mutators
array of strings
deleted
boolean

Indicates whether this metadata was deleted or not.

changed
boolean

Indicates whether changes occurred to this metadata or not.

fields
object

Retrieved extended attribute values. In case of missing fields null values are returned.

exists
object

Map indicating whether given extended attributes exists or not.

Example

application/json
{
  "fileId": "4efc4a0c-0a61-4766-8fe9-c3d7fb414da8",
  "filePath": "/Space1/dir2/file1.txt",
  "seq": 123,
  "fileMeta": {
    "rev": "2-c500a5eb026d9474429903d47841f9c5",
    "mutators": [
      "<<\"p1.1542789098.test\">>"
    ],
    "changed": true,
    "deleted": false,
    "fields": {
      "owner": "john"
    }
  },
  "customMetadata": {
    "rev": "1-09f941b4e8452ef6a244c5181d894814",
    "mutators": [
      "<<\"p1.1542789098.test\">>"
    ],
    "changed": false,
    "deleted": false,
    "exists": {
      "onedata_json": true
    },
    "fields": {
      "key1": "value1"
    }
  }
}
400

Invalid request.

PropertyType & 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.

PropertyType & 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

Oneprovider REST API not available.

PropertyType & 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.

PropertyType & 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
    }
  }
}