Onedata API Reference

REST API references for Onezone, Oneprovider, and Onepanel.

Version:

Onezone REST API Oneprovider REST API Onepanel REST API

Version:

Register file

POST /data/register

Registers a file located on an imported storage. This operation is available only in spaces supported with imported storages with manual import mode enabled. In such setup, the files existing on the storage are not automatically visible in the space and must be registered manually by the space users - learn more.

The operation creates the necessary metadata for the file and registers its physical location on the storage in Onedata, which makes the file visible and accessible within the space. The metadata can be provided explicitly by the registering user, or an automatic detection will be performed (although not all storage backends support the required stat operation or equivalent - in such case some metadata must be provided for the operation to succeed).

The registration of the same file can be repeated, which updates the previous metadata with the new information. In most cases, the metadata is overwritten with new values, with exception of xattrs - previous values are merged with new ones.

This operation requires:

space_register_file privilege

Example cURL requests

Register file

curl -X POST -H "X-Auth-Token: $TOKEN" \
-H 'Content-type: application/json' -d "@./file_spec.json" \
"https://$HOST/api/v3/oneprovider/data/register"

Request body

application/json

Specification of a file to be registered.

Property	Type & Description
spaceId string Id of the space in which the file will be registered - the space must be supported by the storage hosting the file (`storageId`). The space support must have `manual import mode`.
storageId string Id of the storage hosting the file - the storage must support the target space (`spaceId`). The storage must be configured as an `imported storage` with `canonical` path type.
storageFileId string Identifier of the file on storage, relevant for given storage backend: path on POSIX-compatible or canonical object storages, e.g. `/dir/file.txt` URL on HTTP based storages, e.g. `https://www.example.org/data/21/run123.tar`
destinationPath string An absolute path in space where file should be created.
size integer Size of the file in bytes. If not passed, it will be acquired from storage. If storage does not support the `stat` operation or equivalent used for acquiring files metadata, registration will fail if this value is missing.
mode string User defined POSIX file permissions in octal format. If not passed, it will be acquired from storage or default `"664"` mode will be used.
atime integer User defined last access timestamp (in seconds). If not passed, it will be acquired from storage or current timestamp will be used.
mtime integer User defined last modification timestamp (in seconds). If not passed, it will be acquired from storage or current timestamp will be used.
ctime integer User defined last attributes modification timestamp (in seconds). If not passed, it will be acquired from storage or current timestamp will be used.
uid string User defined of the Id of the owner of this file on storage. If not passed, it will be acquired from storage or `0` will be used. This value will be mapped, using LUMA DB, to acquire Onedata user Id of the file owner.
gid string User defined Id of the group owner of this file on storage. If not passed, it will be acquired from storage or `0` will be used. This value will be used as display GID in `getattr` operation.
xattrs object Map with extended attributes key-value pairs which will be attached to newly created file.
json object Map with custom JSON metadata which will be attached to newly created file.
rdf string Base64 encoded RDF metadata which will be attached to newly created file.
autoDetectAttributes boolean Flag which determines whether additional `stat` operation (or equivalent) should be performed on the storage to automatically detect file attributes - they will be used if not provided explicitly in the request. The detection also ensures that the file exists - it is performed if the flag is set to `true`, even if all attributes are provided. If this flag is set to `false`, default attributes are used if not provided explicitly. The only exception is the `size` attribute, which is mandatory. The registration request will fail if `autoDetectAttributes` is set to `false` and `size` is not provided. It is possible to register a file that does not exist on storage if `autoDetectAttributes` is set to `false`. Such file will be visible in Onedata but not accessible.

Request Examples

application/json

{
  "spaceId": "761f76677f42ad5289d6472675d5ecf2dfd57be6",
  "storageId": "2c1e539dbebf76a697e44782787585ebb0f47af1",
  "storageFileId": "https://www.example.org/data/2010/01/05/run123.tar",
  "destinationPath": "/data/2010/01/05/run123.tar",
  "mode": "664",
  "size": 1024,
  "atime": 1464958683054,
  "mtime": 1464958683051,
  "ctime": 1464958681054,
  "uid": 1935313,
  "gid": 1101841,
  "xattrs": {
    "colour": "red",
    "country": "FR",
    "checksum": "189e725f4587b679740f0f7783745056"
  },
  "json": {
    "year": 2014,
    "month": 10,
    "day": 1,
    "run": 5038219,
    "subrun": 1
  },
  "rdf": "PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxyZGY6UkRGIHhtbG5zOnJkZj0iaHR0cDovL3d3dy53My5v cmcvMTk5OS8wMi8yMi1yZGYtc3ludGF4LW5zIyIKICAgICAgICAgICAgeG1sbnM6ZGM9Imh0dHA6 Ly9wdXJsLm9yZy9kYy9lbGVtZW50cy8xLjEvIgogICAgICAgICAgICB4bWxuczpleD0iaHR0cDov L2V4YW1wbGUub3JnL3N0dWZmLzEuMC8iPgoKICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0i aHR0cDovL3d3dy53My5vcmcvVFIvcmRmLXN5bnRheC1ncmFtbWFyIgogICAgICAgICAgICAgZGM6 dGl0bGU9IlJERjEuMSBYTUwgU3ludGF4Ij4KICAgIDxleDplZGl0b3I+CiAgICAgIDxyZGY6RGVz Y3JpcHRpb24gZXg6ZnVsbE5hbWU9IkRhdmUgQmVja2V0dCI+CiAgICAgICAgPGV4OmhvbWVQYWdl IHJkZjpyZXNvdXJjZT0iaHR0cDovL3B1cmwub3JnL25ldC9kYWpvYmUvIiAvPgogICAgICA8L3Jk ZjpEZXNjcmlwdGlvbj4KICAgIDwvZXg6ZWRpdG9yPgogIDwvcmRmOkRlc2NyaXB0aW9uPgoKPC9y ZGY6UkRGPgo=\n",
  "autoDetectAttributes": true
}

Responses

application/json

201

The file has been registered in the Onedata file-system and the result is its Id. Also URI of the new file in form https://$HOST/api/v3/oneprovider/data/{Id} is returned in the response Location header.

Property	Type & Description
fileId string New file Id.

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

At lease one of the required resources (space, storage or file on the storage) does not exist.

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."
}