Agent API

This REST API enables connecting embedded RTOS, windows CE or any other edge-device to Upswift platform.

Register Device

POST https://api.upswift.io/v1/agent/register_device

This is the first call you would have to implement on your edge-device. This call will register your device to Upswift platform.

Request Body

Name	Type	Description
user_token	string	This is your account token. You can find it under the Settings category on the dashboard.
device_identifier	array	This is the identifier of your device. This parameter is a list of Strings. Each string represents an identifier for that device. You can use multiple identifiers for your devices. Usually, it is the MAC addresses of your device. Example: {"device_identifier": ["aa:bb:cc:dd:ee:11", "aa:bb:cc:dd:ee:22"]}
project_name	string	This is the name of the project you would like to register this device to.
device_os	string	This is a string that represents your device operating system. The default value is Agent API.
upswift_version	string	This is a string that represents the Upswift Agent. Since it is your own customization, the value of this MUST begin with: AgentAPI- . The default value is: AgentAPI-v1.
device_name	string	This is the name of your device that will be displayed on the dashboard.
device_group	string	This is the group that you would like to register your device to. This group MUST exist at the dashboard under your project. The default value is Production.
software_version	string	This is the software version that is running on your device. This value will be displayed on the dashboard.

200 Successfully registered the device. The value of the "message" parameter is a JSON object with the keys: 1. device_token - String - This is your device token. Save that value for all future calls.

{"message": {"device_token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"}}

400 Error occurred.

{"error_message": "<ERROR_MESSAGE>"}

429 Rate limit reached.

{}

If you receive status code 350, it means the device has been deleted from the dashboard. You must STOP sending Device Registration and Device Status calls.

Example

Python

import json
import requests

json_content = {'user_token': 'XXXXXXXXXXXXXXX',
                'device_identifier': ['aa:bb:cc:dd:ee:11', 'aa:bb:cc:dd:ee:22'],
                'project_name': 'TestProject',
                'device_os': 'Windows CE',
                'upswift_version': 'AgentAPI-v1',
                'device_name': 'MyDevice1',
                'device_group': 'Test',
                'software_version': '1.0'}

call_request = requests.post("https://api.upswift.io/v1/agent/register_device", json=json_content)
call_response = json.loads(call_request.text)

if call_request.status_code != 200:
    if call_request.status_code == 429:
        error = "API limit reached"
    elif call_request.status_code == 350:
        ### DEVICE IS DELETED
    else:
        error = call_response["message"]
        print(error)
else:
    device_token = call_response["message"]["device_token"]

Project Parameters

GET https://api.upswift.io/v1/agent/project_parameters

This is the second call you would have to implement on your edge-device. This call will provide you the timeout value which represents the timeout between Device Status calls.

Request Body

Name	Type	Description
device_token	string	This is your device token. You have received this value in the response payload of the Register Device call.

200 Successfully registered the device. The value of the "message" parameter is a JSON object with the keys: 1. status_timeout - Integer - This is the timeout time between Device Status calls. (the value is in seconds).

{"message": {"status_timeout": 20}}

400 Error occurred.

{"error_message": "<ERROR_MESSAGE>"}

429 Rate limit reached.

{}

Example

Python

import json
import requests

json_content = {'device_token': 'XXXXXXXXXXXXXXX'}

call_request = requests.get("https://api.upswift.io/v1/agent/project_parameters", json=json_content)
call_response = json.loads(call_request.text)

if call_request.status_code != 200:
    if call_request.status_code == 429:
        error = "API limit reached"
    else:
        error = call_response["message"]
    print(error)
else:
    status_timeout = call_response["message"]["status_timeout"]

Device Status

POST https://api.upswift.io/v1/agent/device_status

This is the third call you would have to implement on your edge-device. This call should be sent every X seconds (depends on the status_timeout value you have received at the Project Parameters API call). This call represents a keep-alive message to Upswift servers, this way the server knows your device is online.

Request Body

Name	Type	Description
device_token	string	This is your device token. You have received this value in the response payload of the Register Device call
ram	integer	This is your current device RAM usage (percentage). For example: a value of 30, will represent 30% RAM usage.
cpu	integer	This is your current device CPU usage (percentage). For example: a value of 88, will represent 88% CPU usage.
disk_usage_total	integer	This is your total space of disk (MB). For example: a value of 400, will represent a total disk of 400MB.
disk_usage_current	integer	This is your current usage of disk (MB). For example: a value of 182, will represent a current disk usage of 182MB.
process_monitor	array	This is a dictionary object representing the processes you monitor. The dict syntax should be as follows: {"<process_name>": true, "<another_process_name>": false} Value of true represent a process that is currently running. false represents a process that is not running. Please make sure to create those processes in the Monitor Processes category before including this parameter.

200 Successfully sent a keep-alive message.

{"message": {"device_token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"}}

400 Error occurred.

{"error_message": "<ERROR_MESSAGE>"}

429 Rate limit reached.

{}

If you receive status code 301, it means that the Project Parameters have been changed. You have to call the Project Parameters call as soon as possible.

Example

Python

import json
import requests

json_content = {'device_token': 'XXXXXXXXXXXXXXX',
                'ram': 33,
                'cpu': 12,
                'disk_usage_total': 1200,
                'disk_usage_current': 180,
                'process_monitor': {"mysql": true,
                                    "my_app": false}}

call_request = requests.post("https://api.upswift.io/v1/agent/device_status", json=json_content)
call_response = json.loads(call_request.text)

if call_request.status_code != 200:
    if call_request.status_code == 429:
        error = "API limit reached"
    elif call_request.status_code == 301:
        ### NEW PROJECT PARAMETERS
    else:
        error = call_response["message"]
        print(error)