API guide

General information

API URL

Access the API by the URL https://domain.com/api/service/api_version/function/.

Where

HTTP-request methods

DCImanager 6 supports GET, POST, and DELETE.

POST-request methods

To send parameters for a POST-request, specify them in the request body in a JSON format.

Response format

A response to API-requests is sent in the form of JSON-objects, e.g.:

Error notification in JSON

{
  "error":
  {
    "code": <error internal code, int>,
    "msg": <error message, string>,
    "value": <additional information, object>
  }
}

How to process code 503

If the platform service is inactive for a long time, it can be suspended. In this case, API requests are terminated with the code 503. Repeat the requests until another code is received in response:

Example on Python 3

from urllib3.util.retry import Retry
from requests import Session
from requests.adapters import HTTPAdapter

HEADER_XSRT_TOKEN = "x-xsrf-token"
HEADER_BOX = "isp-box-instance"
COOKIE_SES6 = "ses6"
# specify id of DCImanager 6 session
SESSION6 = "6BA7C69DCB7DF4DACFFC7E56"


def _make_retry_object():
    """
    Create an object to retry the API:
    total - number of attempts
    backoff_factor - affects the delay between requests
    method_whitelist - a list of methods for which request are repeated
    status_forcelist - list of statuses for which we request are repeated
    ---
  	retries and backoff_factor are selected so that the request does not hang
    for too long
    """
    retries = 10
    return Retry(
        total=retries,
        read=retries,
        connect=retries,
        method_whitelist=['POST', 'GET', 'DELETE'],
        backoff_factor=0.01,
        status_forcelist=[503]
    )


def _make_session():
    """
    Create a request.Session object to retry requests
    """
    session = Session()
    session.verify = False
    session.mount("http", HTTPAdapter(max_retries=_make_retry_object()))
    session.mount("https", HTTPAdapter(max_retries=_make_retry_object()))
    return session


sess = _make_session()
res = sess.get(
    'https://127.0.0.1/api/dci/v3/server/2',
    headers={HEADER_XSRT_TOKEN: SESSION6, HEADER_BOX: 'true'},
    cookies={COOKIE_SES6: SESSION6},
    verify=False
)
res.raise_for_status()
print(res.json())

Authorization methods

There are three levels of API functions:

public functions — they can be called without authorization;
user functions — a user with the "User" access permissions can call the functions;
administrator functions — a user with the "Admin" access permissions can call the functions;

In order to check the user level, DCImanager 6 tries to find the x-xsrf-token parameter and the ses6 cookie-file in the HTTP-heading. They must contain the authorization token for the current user session. To receive the token, use the login/password or key authorization.

Note

If you are running the request locally on the server with the platform, add an HTTP header to the request with the value isp-box-instance: true.

Login and password authorization

Send the POST-request to the URL like https://domain.com/auth/v4/public/token.
Request body in JSON
```
{
  "email": "admin@example.com",
  "password": "secret"
}
```
Comments

admin@example.com — platform administrator email
secret — platform administrator password
Usage in curl
```
curl -X POST 'https://domain.com/api/auth/v4/public/token' -d '{"email": "admin@example.com", "password": "secret"}'
```
Handle the response. It may contain error messages or JSON like this:
Response in JSON
```
{
  "confirmed":true, 
  "id":"24",
  "token":"24-cee181d2-ccaa-4b64-a229-234aa7a25db6"
}
```
Comments

id — token id
token — token number

Use the token that you have received in the heading of the HTTP request. E.g.:

Usage in curl

curl -X POST 'https://domain.com/api/dci/v3/setting/operation_change_boot_order' -H 'Cookie: ses6=24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true' -d '{"value": "true"}'

In the case of error you will receive the following message:
Authorization error
```
{
  "error":
  {
    "code": 3001,
    "msg":"Unauthorized"
  }
}
```

If the authorization token has not been used within 60 minutes, it will be deleted. To get a token with the desired lifetime, send the POST-request to a URL like https://domain.com/auth/v4/token:

Request body in JSON

{
"expires_at": <time>,
"description": <comment>
}

Пояснения

The response will contain a new token with a specified expiration date.

Usage in curl

curl -X POST 'https://domain.com/auth/v4/token' -d '{"expires_at": "2030-01-31 00:00:00", "description": "Token for integration"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'

Changing token and session lifetime

By default, the token and session lifetime is 60 minutes. To change this setting, send a POST request to a URL like https://domain.com/auth/v4/setting/token_ttl:

Request body in JSON

{
"value": "<time>"
}

Comments

Usage in curl

curl -X POST 'https://domain.com/auth/v4/setting/token_ttl' -d '{"value": "999"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a' -H 'Cookie:ses6=4-e9726dd9-61d9-2940-add3-914851d2cb8a'

Key authorization

DCImanager 6 supports throughout user authorization with admin login and password. Eg. it can be used to redirect authorized users from a billing system to DCImanager 6 or to provide temporary access to the platform for a user. The duration of this key is one hour.

Send the POST-request to the URL like https://domain.com/auth/v4/public/token.
Request body in JSON
```
{
  "email": "admin@example.com",
  "password": "secret"
}
```
Comments

admin@example.com — platform administrator email
secret — platform administrator password
Usage in curl
```
curl -X POST 'https://domain.com/api/auth/v4/public/token' -d '{"email": "admin@example.com", "password": "secret"}'
```
Handle the response. It may contain error messages or JSON like this:
Response in JSON
```
{
  "confirmed":true, 
  "id":"24",
  "token":"24-cee181d2-ccaa-4b64-a229-234aa7a25db6"
}
```
Comments

id — token id
token — token number
Send a POST-request to create the key:
Create the authentication key
```
curl -X POST 'https://domain.com/api/auth/v4/user/client@example.com/key'  -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true'  -d '{}'
```
Comments
client@example.com — email of the account for which the key is generated. You can use the account id instead of email
You will receive a JSON-object like this:
Response in JSON
```
{
  "id":"4",
  "key":"4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"
}
```
Comments

id — key id
key — key value

Note

With this key you can give the user temporary access to the platform. The user will be able to log in to the platform via a link in the following format: https://domain.com/auth/key-v4/<key>
Comments

domain.com — domain name or IP address of the server with DCImanager 6
<key> — access key

To get the value of a token using a temporary key, send a POST request:

Receive the session number by the key

curl -k -X POST 'https://domain.com/api/auth/v4/public/key' -H "isp-box-instance: true" -d '{"key": "4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"}'

You will receive the JSON-object like this:

Response in JSON

{
  "confirmed":true,
  "id":"123",
  "token":"1996-0082f9c6-0b07-43ca-b4e7-449c6b0df71f"
}

Comments

Use the token that you have received in the heading of the HTTP request. E.g.:

Usage in curl

curl -X POST 'https://domain.com/api/dci/v3/setting/operation_change_boot_order' -H 'Cookie: ses6=24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true' -d '{"value": "true"}'

In the case of error you will receive the following message:

Authorization error

{
  "error":
  {
    "code": 3001,
    "msg":"Unauthorized"
  }
}

API guide

General information

API URL

HTTP-request methods

POST-request methods

Response format

How to process code 503

Authorization methods

Login and password authorization

Changing token and session lifetime

Key authorization

Related topics