DCImanager Administrator

Guide to API DCImanager

General information


API URL

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

 Where

domain.com — public IP address or the domain of the server with DCImanager

service — internal service for processing requests:

  • auth — authorization service;
  • dci — DCImanager BE — the main service of the control panel;
  • eservice — Equipment service — equipment management service;
  • ipmiproxy — IPMI Proxy service — proxy service for IPMI connections;
  • ip — IPmanager 6 — IP addresses, pools and networks management service

api_version — current version API: v3

function — function to be executed in DCImanager

HTTP-request methods 

DCImanager 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


DCImanager can be suspended if it is not active for a long time. API-requests will be terminated with the code 503. Send the requests again until you receive another code: 

Example on Python 3
def retry(fn, **kwargs):
    response = fn(**kwargs)
    if response.status_code == 503:
        for attempt in range(1, 11):
            time.sleep(0.1 * attempt)
            logging.info(f'Try connect to {kwargs["url"]} number {attempt}')
            response = fn(**kwargs)
            if response.status_code != 503:
                break
    return response

def internal_post(url, data):
    headers = {"Host": "instance-" + os.environ["INSTANCE_ID"], "internal-auth": "on"}
    logging.info(f'Try connect to {url} with headers {headers}')
    retry(requests.post, url=url, json=data, headers=headers)

Authentication methods 


There are three levels of API functions: 

  • public functions — they can be called without authentication;
  • 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 tries to find the ses6 cookie-file in the HTTP-heading. It should contain the id of the current sessions of the user. To receive the session id, use the login/password or key authentication. 

Login and password authentication

  1. To receive a session number, send the POST-request to the URL like https://domain.com/auth/v3/auth

    Request body in JSON
    {
      "email": your_email,
      "password": your_password
    }

    2. Handle the response. It may contain error messages or JSON like this: 

    Response in JSON
    {
      "expires_at": string,
      "id": int,
      "session": string
    }

    3. Use the session number that you have received in the heading of the HTTP request. E.g.: 

    Usage in curl
    curl -k -H "Cookie:ses6=F2BABF12426B297C86FC5628" 'https://domain.com/api/auth/v3/user_exist/client@example.com'

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

    Authorization error
    {
      "error":
      {
        "code": 1114,
        "msg": "Whoami verifired error",
        "value":
        {
          "code": 3002,
          "msg": "Session not found"
        }
      }
    }

Key authentication 

DCImanager supports throughout user authentication with admin login and password. Eg. it can be used to redirect authorized users from BILLmanager to DCImanager.

How it works:

  1. Send a POST-request to create the key. You must have admin permissions to perform this operation:

    Create the authentication key
    curl -X POST 'https://domain.com/api/auth/v3/user/client@example.com/key' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{}'| jq
  2. You will receive a JSON-object like this: 

    Response in JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "key": "94DA5B99AF0BF26D2E96458CABA8DA96"
  3. To get the session number, send the POST-request with the key that you have received: 

    Receive the session number by the key
    curl -X POST 'https://domain.com/api/auth/v3/auth_by_key' -d '{"key": "94DA5B99AF0BF26D2E96458CABA8DA96"}'| jq
  4. You will receive the JSON-object like this: 

    Response in JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "id": 2,
      "session": "CC033C4629BAEF3852CFE27A"
    }

Current session management


Receive information about the current session

  1. Send a GET-request with the number of the current session: 

    Receive informaion about the current session
    curl -X GET 'https://domain.com/api/auth/v3/whoami' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. You will receive the JSON-object like this:

    Response in JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "lang": "ru",
      "owner_email": "client@example.com",
      "owner_id": 2,
      "roles": [
        "@user"
      ],
      "ses_id": 2,
      "session": "CC033C4629BAEF3852CFE27A",
      "trustee_email": "client@example.com",
      "trustee_id": 2
    }

Terminate the session 

We recommend terminating a user session after you have completed your API operations: 

  1. Send a DELETE-request with the session number: 

    Close the session
    curl -X DELETE 'https://domain.com/api/auth/v3/session/CC033C4629BAEF3852CFE27A' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. You will receive a JSON-object like this:

    Response in JSON
    {
      "status": "ok"
    }
  3. When trying to use the session that has been already deleted you will receive a JSON-object like the following: 

    Session not found
    {
      "error": {
        "code": 3002,
        "msg": "Session not found"
      }
    }