Docluster API manual

Basic concepts of the API mechanism.

The system is managed using the HTTP protocol.

The principle of requests is based on requests for piti and POST data.

Authorization is required before starting work with the API. After successful authorization, the client will be given an access token, which will be used to authorize all other requests.
With each request, you must pass an access token as a parameter.

Request Structure

http://<cluster>:<port>/api/<path>

POST data: "access_token" = <access_token>

 

The response from the server will be in the form of standard JSON.

{
 "msg": "",
 "status": "",
 "error": ""
}

msg - Returns the data requested by the request, if successful.

status - Request status. Returns the following values: error, success, true, fals

error - Returns the error text.

 

 

Login and logout

You must be logged in before starting to work with the API.

After successful authorization, an access token will be returned, which will be required for all other requests.

The default token is valid for 10 minutes and is extended by 10 minutes from the last use.
Attention: the access token is valid only with the client's IP address.

If the token has expired. You need to complete the authorization procedure and get a new token.

 

Login

Request Structure:

http://<cluster>:<port>/api/login

Post data:

username = <api_login>
password = <api_apss>

The response from the server:

{
 "msg": {
  "access_token": "ISGYCHKMVPFPLSDRDTJGYDSQVWGHSOMPUERUMFBSMJOGUHRCAUDCCRCBGBVN"
 },
 "status": "success",
 "error": ""
}

Errors:

-Username not found, please log in.
-Wrong password.

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
api_login = ''
api_apss = ''
access_token = ''

def login():
    global access_token
    send_token = requests.post(url=api_url+'login/', data={"access_token": access_token})
    answer_token = json.loads(send_token.text)
    if answer_token['status'] == 'success':
        print("Authorized on " +  api_url)
    if answer_token['status'] == 'error':
        print("Not authorized")
        print("Login request to "+api_url)
        send_login = requests.post(url=api_url+'login/', 
                                   data={"username": api_login, "password": api_apss})
        answer_login = json.loads(send_login.text)
        print(send_login.text)
        if answer_login['status'] == 'success':
            access_token = answer_login['msg']['access_token']
            f = open('access_token.tmp', 'w+')
            f.write(access_token)
            f.close()
            print("Authorization was successful to " + api_url)
        else:
            print("Failed login to " + api_url)
            print("Error: " + answer_login['error'])

 

 

Logout

 

Request Structure:

http://<claster>:<port>/api/logout

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": "",
 "status": "success",
 "error": ""
}

Errors:

-Token not found, please log in.
-The token is not important for this IP address, please log in.
-Token expired please log in.

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

def logout():
    send_logout = requests.post(url=api_url + 'logout', data={"access_token": access_token})
    answer_logout = json.loads(send_logout.text)
    if answer_logout['status'] == 'success':
        print("Logout " + api_url)
    else:
        print("Error: " + answer_logout['error'])

 

 

 

 

system

system

System users

Сreate a new user

Request Structure:

http://<cluster>:<port>/api/system/users/add

Post data:

access_token = <access_token>
username = testuser
password = testpass

The response from the server:

{
 "msg": {
  "testuser": {
   "password": "179ad45c6ce2cb97cf1029e212046e81"
  }
 },
 "status": "success",
 "error": ""
}

Errors:

-user already exists
-username and password must not be empty

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/users/add'
data = {
        'username': 'testuser',
        'password': 'testpass'
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

Delete user

Request Structure:

http://<cluster>:<port>/api/system/users/delete

Post data:

access_token = <access_token>
username = testuser

The response from the server:

{
 "msg": {},
 "status": "success",
 "error": ""
}

Errors:

-user does not exist
-Can not delete last user

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/users/delete'
data = {
        'username': 'testuser'
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

Set new user data

Request Structure:

http://<cluster>:<port>/api/system/users/set

Post data:

access_token = <access_token>
username = testuser
password = newtestpass
email = testuser@clastercp.com

The response from the server:

{
 "msg": {
  "testuser": {
   "password": "37b032c83f249979fc5db9b0b391ef4a",
   "email": "testuser@clastercp.com"
  }
 },
 "status": "success",
 "error": ""
}

Errors:

-user does not exist

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/users/set'
data = {
        'username': 'testuser',
        'password': 'newtestpass',
        'email': 'testuser@clastercp.com'
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

Get user data

Request Structure:

http://<cluster>:<port>/api/systems/users/get

Post data:

access_token = <access_token>
username = testuser

The response from the server:

{
 "msg": {
  "testuser": {
   "password": "37b032c83f249979fc5db9b0b391ef4a",
   "email": "testuser@clastercp.com"
  }
 },
 "status": "success",
 "error": ""
}

Errors:

-user does not exist

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/users/get'
data = {
        'username': 'testuser'
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

Get all users data

Request Structure:

http://<cluster>:<port>/api/system/users/get

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": {
  "admin": {
   "password": "21232f297a57a5a743894a0e4a801fc3"
  },
  "testuser": {
   "password": "37b032c83f249979fc5db9b0b391ef4a",
   "email": "testuser@clastercp.com"
  }
 },
 "status": "success",
 "error": ""
}

Errors:

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/users/get'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

system

System hosts

Add a new host

Request Structure:

http://<cluster>:<port>/api/system/hosts/set

Post data:

access_token = <access_token>
ip = 1.2.3.4
hostname = docluster.com

The response from the server:

{
 "msg": {
  "1.2.3.4": [
   "ducluster.com"
  ]
 },
 "status": "success",
 "error": ""
}

Errors:

-hostname already added
-wrong IP or hostname format

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/hosts/set'
data = {
        'ip': '1.2.3.4',
        'hostname': 'clastercp.com'
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

Delete host from hosts

Request Structure:

http://<cluster>:<port>/api/system/hosts/delete

Post data:

access_token = <access_token>
ip = 1.2.3.4
hostname = docluster.com

The response from the server:

{
 "msg": {},
 "status": "success",
 "error": ""
}

Errors:

-wrong IP or hostname format
-ip not definite in hosts

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/hosts/delete'
data = {
        'ip': '1.2.3.4',
  		'hostanme': 'docluster.com'
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

Get all hosts

Request Structure:

http://<cluster>:<port>/api/system/users/get

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": {
  "1.2.3.1": [
   "node-1",
   "node-1.docluster.com"
  ],
  "1.2.3.2": [
   "node-2",
   "node-2.docluster.com"
  ],
  "1.2.3.3": [
   "node-3",
   "node-3.docluster.com"
  ],
  "1.2.3.4": [
   "node-4",
   "node-4.docluster.com"
  ],
  "1.2.3.5": [
   "node-5",
   "node-5.docluster.com"
  ]
 },
 "status": "success",
 "error": ""
}

Errors:

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/hosts/get'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

system

System config

get|save|read config

get - Returns the current configuration

save - Writes the configuration to a file and changes the configuration number to 1 up. Returns the current configuration

read - Read a configuration from a file. Returns the current configuration.

Request Structure:

http://<cluster>:<port>/api/system/config/<get|save|read>

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": {
  "version": 2,
  "system": {
   "users": {
    "admin": {
     "password": "21232f297a57a5a743894a0e4a801fc3"
    }
   }
  },
  "cluster": {
   "name": "DoCluster",
   "nodes": {
    "node-2.docluster.com": {
     "machine": "x86_64",
     "API_key": "ippowcalrksmufirthcntewujgndhy",
     "MNG_IP": "192.168.129.82"
    },
    "node-3.docluster.com": {
     "machine": "x86_64",
     "API_key": "ikdeiwnlhtswnxxuybfssxzoknhiyb",
     "MNG_IP": "192.168.129.83"
    },
    "node-4.docluster.com": {
     "machine": "x86_64",
     "API_key": "rwlozmuxekgqxahwzxsenbdmgaejvy",
     "MNG_IP": "192.168.129.84"
    }
   }
  },
  "quorum": {
   "nodes": [
    "node-2.docluster.com",
    "node-3.docluster.com",
    "node-4.docluster.com"
   ]
  }
 },
 "status": "success",
 "error": ""
}
{
 "version": 2,
 "system": {
  "users": {
   "admin": {
    "password": "21232f297a57a5a743894a0e4a801fc3"
   }
  }
 },
 "cluster": {
  "name": "DoCluster",
  "nodes": {
   "node-2.docluster.com": {
    "machine": "x86_64",
    "API_key": "ippowcalrksmufirthcntewujgndhy",
    "MNG_IP": "192.168.129.82"
   },
   "node-3.docluster.com": {
    "machine": "x86_64",
    "API_key": "ikdeiwnlhtswnxxuybfssxzoknhiyb",
    "MNG_IP": "192.168.129.83"
   },
   "node-4.docluster.com": {
    "machine": "x86_64",
    "API_key": "rwlozmuxekgqxahwzxsenbdmgaejvy",
    "MNG_IP": "192.168.129.84"
   }
  }
 },
 "quorum": {
  "nodes": [
   "node-2.docluster.com",
   "node-3.docluster.com",
   "node-4.docluster.com"
  ]
 }
}

Errors:

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/config/<get|save|read>'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

 

system

System loops

get loops

get - Returns the current status of all running software loops.

Request Structure:

http://<cluster>:<port>/api/system/loop/get

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": {
  "quorum-Loop_QuorumStatus": {
   "isAlive": true,
   "counter": 19,
   "ident": "140645146556160",
   "native_id": "23681",
   "timeout": "3"
  },
  "cluster-Loop_NodesStatus": {
   "isAlive": true,
   "counter": 15,
   "ident": "140645138163456",
   "native_id": "23682",
   "timeout": "5"
  }
 },
 "status": "success",
 "error": ""
}

Errors:

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/loop/get'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)
system

System tasks

Get all tasks without log

Request Structure:

http://<cluster>:<port>/api/system/tasks/get

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": [
  {
   "id": "ntmjhibjazlkmlrmbwpgdgeilcwyvf",
   "node": "PC-ruslan",
   "user": "ruslan",
   "description": "Set /etc/hosts",
   "module": "system",
   "method": "hostsset",
   "queue": true,
   "status": "error",
   "process_id": "60480",
   "start": "09-05-2022 19:34:58",
   "end": "09-05-2022 19:35:02",
   "duration": "3"
  },
  {
   "id": "svipiesvlrplfuvbgcilcvimotekqz",
   "node": "node-2.docluster.com",
   "user": "ruslan",
   "description": "Set /etc/hosts",
   "module": "system",
   "method": "hostsset",
   "queue": true,
   "status": "success",
   "process_id": "79574",
   "start": "09-05-2022 19:34:58",
   "end": "09-05-2022 19:35:02",
   "duration": "3"
  },
  {
   "id": "cavohdzoqabtmqaofmdgtskggdwjne",
   "node": "PC-ruslan",
   "user": "ruslan",
   "description": "Set /etc/hosts",
   "module": "system",
   "method": "hostsset",
   "queue": true,
   "status": "error",
   "process_id": "60558",
   "start": "09-05-2022 19:36:07",
   "end": "09-05-2022 19:36:11",
   "duration": "4"
  },
  {
   "id": "hvrombzgewntoyewhywgseldmwywmo",
   "node": "node-2.docluster.com",
   "user": "ruslan",
   "description": "Set /etc/hosts",
   "module": "system",
   "method": "hostsset",
   "queue": true,
   "status": "success",
   "process_id": "79623",
   "start": "09-05-2022 19:36:08",
   "end": "09-05-2022 19:36:11",
   "duration": "3"
  }
 ],
 "status": "success",
 "error": ""
}

Errors:

-no tasks in the system

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/tasks/get'
data = {
        'ip': '1.2.3.4',
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

Get all task data per id

Request Structure:

http://<cluster>:<port>/api/system/tasks/get

Post data:

access_token = <access_token>
id = <task id>

The response from the server:

{
 "msg": [
  {
   "id": "ntmjhibjazlkmlrmbwpgdgeilcwyvf",
   "node": "PC-ruslan",
   "user": "ruslan",
   "description": "Set /etc/hosts",
   "module": "system",
   "method": "hostsset",
   "arg": {
    "192.168.129.198": [
     "PC-ruslan"
    ],
    "192.168.129.81": [
     "node-1.docluster.com"
    ],
    "192.168.129.82": [
     "node-2.docluster.com"
    ],
    "192.168.129.83": [
     "node-3.docluster.com"
    ],
    "192.168.129.84": [
     "node-4.docluster.com"
    ],
    "192.168.129.85": [
     "node-5.docluster.com"
    ],
    "192.168.129.86": [
     "node-6.docluster.com"
    ],
    "192.168.129.87": [
     "node-7.docluster.com"
    ],
    "192.168.129.88": [
     "node-8.docluster.com"
    ],
    "192.168.129.89": [
     "node-9.docluster.com"
    ],
    "192.168.129.90": [
     "node-10.docluster.com",
     "node-10.docluster.comq"
    ]
   },
   "queue": true,
   "status": "error",
   "process_id": "60480",
   "start": "09-05-2022 19:34:58",
   "end": "09-05-2022 19:35:02",
   "duration": "3",
   "log": "Task: ntmjhibjazlkmlrmbwpgdgeilcwyvf\nModule: system\nMethod: hostsset\nDescription: Set /etc/hosts\nUser: ruslan\n-------------------------------------\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\n/bin/sh: 1: cannot create /etc/hosts: Permission denied\n\nTask: error\n"
  }
 ],
 "status": "success",
 "error": ""
}

Errors:

-no tasks in the system

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/tasks/get'
data = {
        'id': <task id>
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

 

Stop task per id

Request Structure:

http://<cluster>:<port>/api/system/tasks/stop

Post data:

access_token = <access_token>
id = <task id>

The response from the server:

{
 "msg": [],
 "status": "success",
 "error": ""
}

Errors:

-no tasks in the system

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'system/tasks/stop'
data = {
        'id': <task id>,
}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

 

 

cluster

cluster

Create cluster

To create a new cluster, you need to log in.

Request Structure:

http://<cluster>:<port>/api/claster/create

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": "Cluster created successfully",
 "status": "success",
 "error": ""
}

Errors:

-cluster already created

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'cluster/create'
data = {}


def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    

send(path, data)

 

cluster

Join cluster

To join to cluster, you need to log in.

Request Structure:

http://<cluster>:<port>/api/claster/join

Post data:

access_token = <access_token>
cluster_username = <username>
cluster_password = <password>
cluster_ip = <IP>

The response from the server:

{
 "msg": <cluster config>,
 "status": "success",
 "error": ""
}

Errors:

-cluster not created on connecting node
-missing data
-username not found
-password is wrong
-a node with the same hostname is already in the cluster

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'cluster/join'
data = {
    'cluster_username': 'admin',
    'cluster_password': 'admin',
    'cluster_ip': '192.168.129.81',
}


def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    

send(path, data)

 

 

 

 

cluster

Cluster status

Cluster status

Returns the status of all nodes in the cluster with load parameters and additional information.

Request Structure:

http://<cluster>:<port>/api/cluster/status

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": {
  "status": "OK",
  "errors": [],
  "nodes": {
   "node-2.docluster.com": {
    "config_version": 3,
    "cpu_percent": 1.8,
    "memory_percent": 24.3,
    "memory_available": "739.6M",
    "memory_used": "83.4M",
    "memory_total": "976.4M",
    "errors": [],
    "status": "success"
   },
   "node-3.docluster.com": {
    "config_version": 3,
    "cpu_percent": 1.6,
    "memory_percent": 23.7,
    "memory_available": "744.7M",
    "memory_used": "78.4M",
    "memory_total": "976.4M",
    "errors": [],
    "status": "success"
   },
   "node-4.docluster.com": {
    "config_version": 3,
    "cpu_percent": 1.6,
    "memory_percent": 23.7,
    "memory_available": "744.6M",
    "memory_used": "78.4M",
    "memory_total": "976.4M",
    "errors": [],
    "status": "success"
   }
  }
 },
 "status": "success",
 "error": ""
}

Errors:

-<X> MNG nodes are not online

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'cluster/status'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

quorum

quorum

Quorum status

Request Structure:

http://<cluster>:<port>/api/quorum/status

Post data:

access_token = <access_token>

The response from the server:

{
 "msg": {
   "status": "OK",
   "error": "",
   "master": "node-2.docluster.com",
   "nodes": [
    {
     "node": "node-2.docluster.com",
     "status": "online",
     "error": "",
     "config_version": 8
    },
    {
     "node": "node-3.docluster.com",
     "status": "online",
     "error": "",
     "config_version": 8
    },
    {
     "node": "node-4.docluster.com",
     "status": "online",
     "error": "",
     "config_version": 8
    }
   ]
 },
 "status": "success",
 "error": ""
}

Errors:

-<X> MNG nodes are not online

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'quorum/status'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

quorum

Quorum nodes

To add or remove cluster nodes to the quorum.

add node

Request Structure:

http://<cluster>:<port>/api/quorum/add

Post data:

access_token = <access_token>
node = <node-name>

The response from the server:

{
 "msg": {},
 "status": "success",
 "error": ""
}

Errors:

-node already in quorum
-node is not in cluster

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'quorum/nodes/add'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)

 

delete node

Request Structure:

http://<cluster>:<port>/api/quorum/delete

Post data:

access_token = <access_token>
node = <node-name>

The response from the server:

{
 "msg": {},
 "status": "success",
 "error": ""
}

Errors:

-can not delete master node
-node is not in cluster
-node is not in quorum

Example:

import requests
import json

api_url = "http://<IP>:<PORT>/api/"
access_token = 'BLABLALBA'

path = 'quorum/nodes/delete'
data = {}

def send(path, data):
    data['access_token'] = access_token
    send = requests.post(url=api_url + path, data=data)
    print(send.text)
    
send(path, data)