Applies to: JovianDSS up32 and up33 (single-node and HA cluster); older versions see section 3
Summary
JovianDSS can be managed remotely through a REST API over HTTPS. This article shows how to enable the API, which address and credentials to use, which API version your JovianDSS version answers, and where to get the API reference. The reference is attached to this article.
1. Enable REST API access
REST API access is disabled by default. Enable it in the web GUI:
- Go to System Settings > Administration, section REST API access.
- Tick Enable REST API access.
- Keep the default Port (82) or enter another free port.
- Set the Username (default
admin) and a Password, and type the password again to confirm it. There is no default password. The password has to be typed again every time a change in this section is applied.
- Click Apply.
The REST API username and password are separate from the GUI administrator password.
To allow reading only, tick Read-only next to Access restriction: GET and HEAD requests are then accepted, and every other request is refused with HTTP 405.
REST API access can also be enabled from the local console: press Ctrl+Alt+T, choose Web services management > Access settings, tick Enable REST API access (port 82), select Apply and confirm the warning. The console cannot set a password; it keeps the REST API credentials set in the GUI.
2. Connect
|
|
| Base URL |
https://<JovianDSS_IP>:82/api/v4/ (use your port if you changed it) |
| Authentication |
HTTP Basic, with the REST API username and password from step 1 |
| Format |
JSON; send Content-type: application/json with every request that has a body |
The paths in the API reference are relative: the reference shows /pools, the full address is https://<JovianDSS_IP>:82/api/v4/pools.
Example, listing the pools:
curl -k -u admin:<password> -H "Content-type: application/json" https://<JovianDSS_IP>:82/api/v4/pools
Port 82 uses the same certificate as the web GUI. With the default self-signed certificate, add -k to curl. A custom certificate installed in the HTTPS Certificate section of System Settings > Administration applies to the REST API as well.
A DELETE request without a body must not carry the Content-type header (or must send {} as its body); otherwise it is refused with HTTP 400.
On an HA cluster each node answers the REST API on its own address. Pool calls such as GET /api/v4/pools list only the pools imported on the node you call, while cluster calls such as GET /api/v4/cluster/resources give the same answer on either node. A pool's virtual IP reaches the node that currently holds the pool and follows the pool when it moves to the other node; during the move it does not answer for a short time.
Calls that return a list are paged. The reference lists the query parameters each call accepts, usually page and per_page, plus sort_by and order on many calls.
Long-running operations
Calls that support it can run in the background: add ?as_task=1 to the URL. The answer is then HTTP 202 with a task ID. Check the task with GET /api/v4/tasks/<task_id> until its status is succeeded; GET /api/v4/tasks/<task_id>/response then returns the status and body the call would have returned (until the task has finished it answers 404). Tasks that report progress also answer GET /api/v4/tasks/<task_id>/progress. GET /api/v4/tasks lists tasks; its pages are numbered from 0.
3. Which API version to use
| JovianDSS version |
API |
| up30 and later |
/api/v4 is the current API. /api/v3 is only partially supported: not all operations can be run through it. |
| up29 and earlier |
/api/v3 only. /api/v4 does not exist on these versions and returns HTTP 404. |
Open-E supports the current JovianDSS version and the one before it, currently up33 and up32. Both use /api/v4; write new scripts against it. A system on an older version should be updated to a supported version, and its /api/v3 scripts moved to /api/v4.
4. API reference
Two references are attached to this article; download them from Attached files at the bottom of this page:
| File |
For |
JovianDSS-up33-REST-API-v4-reference.zip |
JovianDSS up33 and up32, API v4: the current reference |
JovianDSS-up29-REST-API-v3-reference.zip |
JovianDSS up29, API v3: for reference only, while existing scripts are moved to v4 |
To read a reference, unzip it and open index.html in a web browser. Calls are grouped by resource (pools, cluster, services, and so on); click a call to show its description and the JSON schema of its request body. "Schema N/A" means the reference documents no request body for that call. There is no OpenAPI (Swagger) file.
The pool encryption calls (/pools/<pool_name>/encryption-settings and /pools/<pool_name>/change-encryption-password) exist only on up33. A reference can also list calls that a given system does not offer, for example for a feature that is not enabled; such a call answers HTTP 404.
On up33 the system can also generate its own reference: open https://<JovianDSS_IP>:82/api/v4/doc and log in with the REST API credentials, or download it as a ZIP from https://<JovianDSS_IP>:82/api/v4/doc/download.
Related articles