Overview

This is the RESTful API definition of Onepanel 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.

This API allows control and configuration of local Onedata deployment, in particular full control over the Onezone and Oneprovider services and their distribution and monitoring on the local resources.

The API is grouped into 3 categories of operations:

• Onepanel - for common operations
• Oneprovider - for Oneprovider specific administrative operations
• Onezone - for Onezone specific administrative operations

Each of these components is composed of the following services:

• Worker services - these are available under /zone/workers and /provider/workers paths,
• Databases services - each Onedata component stores it's metadata in a Couchbase backend, which can be distributed on any number of nodes, these are available under /zone/databases and /provider/databases paths,
• Cluster manager services - this is a service which controls other deployed processes in one site, these are availables under these are available under /zone/managers and /provider/managers paths.

Onezone and Oneprovider components are composed of 3 types of services: managers, databases and workers.

Using this API each of these components can be deployed, configured, started and stopped on a specified host in the local site, in the context of either Onezone or Oneprovider service.

All paths listed in this documentation are relative to the base Onepanel REST API which is /api/v3/onepanel, so complete URL for a request to Onepanel service is:

http://HOSTNAME:PORT/api/v3/onepanel/...

Authentication

Token authentication

The recommended, safest way of authenticating requests to Onepanel API is using the Onedata access tokens. The token should be present in X-Auth-Token or Authorization: Bearer header. See Onezone documentation for detailed explanation of the token concepts.

Curl examples:

curl -H "X-Auth-Token: $TOKEN" [...]
curl -H "Authorization: Bearer $TOKEN" [...]
curl -H "Macaroon: $TOKEN" [...]   # DEPRECATED

Passphrase authentication

The token authentication dependes on the Onezone service. In special cases - during Onezone deployment or its outage - it is necessary to use the local emergency passphrase.

The passphrase should be provided in a Basic authentication header with username onepanel. For curl users this means

curl -u onepanel:TheEmergencyPassphrase

The passphrase can also be sent without any username, as the whole content of base64-encoded string in Basic authorization header, e.g.

curl -H "Authorization: Basic $(echo -n TheEmergencyPassphrase | base64)"

The passphrase is set during deployment. It can be changed in the Onepanel GUI or with an API request:

curl -X PUT 'https://$HOST:9443/api/v3/onepanel/emergency_passphrase' \
-u onepanel:TheEmergencyPassphrase -H 'Content-Type: application/json' \
-d '{"currentPassphrase": "TheEmergencyPassphrase", "newPassphrase": "TheNewPassphrase"}'

API structure

The Onepanel API is structured to reflect that it can either be used to control Onezone or Oneprovider deployment, each Onedata component deployment has a separate Onepanel instance. In order to make the API calls explicit, Onezone or Oneprovider specific requests have different paths, i.e.:

• Onezone specific operations start with /api/v3/onepanel/zone/
• Oneprovider specific operations start with /api/v3/onepanel/provider/
• Common operations paths include /api/v3/onepanel/users, /api/v3/onepanel/hosts and /api/v3/onepanel/tasks

The overall configuration of each component can be controlled by updating /api/v3/onepanel/zone/configuration and /api/v3/onepanel/provider/configuration resources.

Examples

Below are some example requests to Onepanel using cURL:

Add storage resource to provider

curl -X POST -u onepanel:Passphrase1 -k -vvv -H "content-type: application/json" \
-d '{"NFS": {"type": "posix", "mountPoint": "/mnt/vfs"}}' \
https://172.17.0.4:9443/api/v3/onepanel/provider/storages

Add a new Onezone worker

curl -X POST -u onepanel:Passphrase1 -k -vvv -H "content-type: application/json" \
-d '{"hosts": ["node1.p1.1.dev"]}' \
https://172.17.0.4:9443/api/v3/onepanel/zone/workers