Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Version:

Onezone REST API Oneprovider REST API Onepanel REST API

Version:

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 -X POST -d "@./changes_req.json" -H "X-Auth-Token: $TOKEN" \
"https://$HOST/api/v3/oneprovider/changes/metadata/$SPACE_ID"

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.

Property Type & 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 Xattrs 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 Xattrs 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.

Property Type & 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 File type. Enum: REGDIR
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 occured to this metadata or not.
fields object Retrieved xattr values. In case of missing fields `null` values are returned.
exists object Map indicating whether given xattrs 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.

Property	Type & Description
error string Identifier representing internal error code.
error_description string Detailed error message.

Example

application/json

{
  "error": "invalid_token",
  "error_description": "Provided token could not be validated."
}

403

Forbidden request.

Property	Type & Description
error string Identifier representing internal error code.
error_description string Detailed error message.

Example

application/json

{
  "error": "invalid_token",
  "error_description": "Provided token could not be validated."
}

404

Oneprovider REST API not available.

Property	Type & Description
error string Identifier representing internal error code.
error_description string Detailed error message.

Example

application/json

{
  "error": "invalid_token",
  "error_description": "Provided token could not be validated."
}

500

Internal server error.

Property	Type & Description
error string Identifier representing internal error code.
error_description string Detailed error message.

Example

application/json

{
  "error": "invalid_token",
  "error_description": "Provided token could not be validated."
}