Overview

This is the RESTful API definition of Oneprovider component of Onedata data management system onedata.org.

This API is defined using Swagger, the JSON specification can be used to automatically generate client libraries - swagger.json.

In addition to REST API, Oneprovider also provides support for CDMI protocol. Keep in mind that CDMI is less performant, mainly because it uses Base64 encoded strings for binary file content transmission, resulting in approximately 33% larger I/O traffic compared to REST, which works with plain binaries.

Authentication

To use the APIs, the REST client must authenticate with the Oneprovider service and present a proof of authorization to perform a specific operation. This is done using access tokens, which can be generated using the Onedata GUI or Onezone's REST API.

The token is passed in the request header like this:

X-Auth-Token: MIIFrzCCA5egAwIBAgIBEzANBgkqhkiG9w0BAQUFADBcMQswCQYDVQQGEwJQTDET...

The authorization to perform a specific operation depends on the authenticated user's privileges in the corresponding space, file level permissions (posix, ACL) and caveats (restrictions) inscribed in the provided access token.

Data management basics

The Onedata system organizes all user data into logical containers called spaces.

Any file in Onedata (regular, directory, symbolic link, or hard link) can be globally identified using its unique File Id or logical path.

All logical paths in Onedata use the slash (/) delimiter and must start with a leading slash and a space name:

/CMS 1/directory/images&videos/garden.png

File Id is a unique, global identifier associated with a file, structured as a string of alphanumeric characters:

094576776E667431723230677767776C6B497031394E445F6E3868677873...

The path-based navigation is used mainly in the Web GUI and Oneclient interfaces. In the REST and CDMI APIs, it is recommended to use File IDs, due to better performance and no need for escaping or encoding.

Find out the File Id

Web GUI - click on Information in the file/directory context menu and look for File Id.

REST API - use the File Id resolution endpoint. Below example returns the File Id of
/CMS 1/directory/images&videos/garden.png, where CMS 1 is the space name:

curl -H "X-Auth-Token: ${ACCESS_TOKEN}" -X POST \
"https://${PROVIDER_DOMAIN}/api/v3/oneprovider/lookup-file-id/CMS%201/directory/images%26videos/garden.png"

{
  "fileId": "094576776E667431723230677767776C6B497031394E445F6E3868677873..."
}

NOTE: Paths used in URLs must be url-encoded, e.g.:

{...}/CMS%201/directory/images%26videos/garden.png

Space Id

Space Id is a unique, global identifier associated with a space and can be used universally in the REST APIs. In order to find out the Space Id:

Web GUI - click on Information in the file/directory context menu and look for Space Id.

REST API - use the Get all user spaces endpoint.

The Space Id can be used interchangeably with the space root directory's File Id in the path-based enpoints.

Remove specific file relative to the space root

curl -H "X-Auth-Token: $TOKEN" -X DELETE "https://$PROVIDER_HOST/api/v3/oneprovider/data/$SPACE_ID/path/dir1/file.txt"
# is equivalent to
curl -H "X-Auth-Token: $TOKEN" -X DELETE "https://$PROVIDER_HOST/api/v3/oneprovider/data/$SPACE_ROOT_FILE_ID/path/dir1/file.txt"

Remove specific file relative to any parent directory

curl -H "X-Auth-Token: $TOKEN" -X DELETE "https://$PROVIDER_HOST/api/v3/oneprovider/data/$PARENT_FILE_ID/path/dir1/file.txt"

API structure

The API is divided into the following sections:

Space management

These methods provide means for getting basic information about spaces directly from the Oneprovider service, but also allows to define database views.

File access and management

The API provides capabilities for:

• browsing files in spaces and directories,
• creating and deleting files as well as updating their content
• querying for file attributes, such as 'mode' file permissions and updating them,
• managing custom file metadata (extended attributes, JSON, RDF),
• manual registration of files for imported storage backends.

More information can be found here.

Replica and QoS management

These methods allow viewing file replica distribution, requesting file replication (transfers) between Oneproviders, viewing ongoing and historical transfers data, as well as managing QoS requirements that trigger automatic replication according to the QoS rules.

Share management

Offers methods for creating, modyfying and deleting shares. Shares are files or directories that were made publicly available, so that they can be viewed by everyone through a public URL.

Dataset & archive management

API for managing datasets - designated files or directories that are used to facilitate building collections of data meaningful for the users with additional features, such as write protection and archivisation mechanisms.

Automation

Basic API for scheduling and viewing workflow executions.

Monitoring

The API provides means for subscribing (through HTTP long-polling technique) for file related events such as reads, writes or deletes which are returned as complete file metadata records with sequence numbers representing their current version.

Service information

Publicly available, basic configuration of the Oneprovider service.

Detailed examples of API usage are available in the documentation of each operation.