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.

All paths below are relative to a common Oneprovider basepath which is /api/v3/oneprovider, thus a complete example query for 'mode' file attributes would be:

https://ONEPROVIDER_HOSTNAME/api/v3/oneprovider/data/$FILE_ID?attribute=mode

Please note that currently the default port for Oneprovider instances is 443.

In addition to REST API, Oneprovider also provides support for CDMI protocol, and some of data management operations are currently only possible via CDMI.

Authentication

In order to be able to use this API the REST client must be able to authenticate with the Oneprovider service.

Currently this is supported through authentication token which can be generate using the Onedata user interface. The token must be added to the request header like this:

X-Auth-Token: LAKSJHDLKJAHSDKLJHASKLCBBASKLCBLHABSCBALKSBCK...

In case this Onedata deployment supports authentication delegation other IdP's, the X-Auth-Token field can contain token from such IdP with appropriate prefix, as configured by Onezone administrators, e.g.:

  X-Auth-Token: github:GST5aasdA7asdAASFG7asdasaAS

In addition please take into account, that depending on your account authorization rights, not all operations may be possible.

API structure

The Oneprovider API reflects the fact that most operations deal directly with virtual file paths relative to user spaces, which are provided as part of the paths in the REST calls.

The API provides the following functionality:

Data

File information

The /data/ path methods provide basic capability for:

• browsing files in spaces and directories,
• querying for file attributes, such as 'mode' file permissions and updating them,
• managing file metadata.

Share information

The /share/ methods enable creating, modyfying and deleting shares. Shares are directories that were made publicly available, so they can be viewed by everyone through public URL.

Space information

The /space/ methods provide means for getting basic information about spaces directly from the Oneprovider service but also allows to define views and list transfers for specified space.

Replication

Replica management

The /replicas/ methods allow retrieving information about file replica distribution among Onedata providers as well as requesting specific file replication to selected providers.

Transfer management

The /transfer/ operations provide basic transfer management functionality based on the Id of transfer returned by /replicas/{path} [POST] operation.

Monitoring

Changes subscription

The /changes/ method group 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.

Monitoring metrics

The /metrics/ operations enable retrieval of internal Oneprovider monitoring data. All monitoring data is returned in the form of RRD database files, with resolution determined by the step query parameter.

Examples

Create replica of file at specific storage provider

curl -v --tlsv1.2 -H "X-Auth-Token: $TOKEN" -X POST \
"https://$PROVIDER/api/v3/oneprovider/replicas/MySpace1/MyFile2.txt?provider_id=$PROVIDER_ID"

Get space storage qouta metric

curl -v --tlsv1.2 -H "X-Auth-Token: $TOKEN" -X GET \
"https://$PROVIDER/api/v3/oneprovider/metrics/space/MySpace1?metric=storage_qouta"

More detailed examples are available in the documentation of each operation.