Agent API

Last updated: March 12th, 2020

General

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

Please note - Agent API is open only for prototyping and for paying accounts subscribed to the Special Plan. Contact our team for more information regarding the Agent API - contact@upswift.io

Device

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.

URL: https://api.upswift.io/v1/agent/register_device
Request Type: POST
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_identifier - Required - List - This is the identifier of your device. This parameter is a list of Strings. Each string represent 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 - Required - String - This is the name of the project you would like to register this device to.
  • device_os - Optional - String - This is a string that represents your device operating system. Default value is Agent API.
  • upswift_version - Optional - 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 - Optional - String - This is the name of your device that will be displayed at the dashboard.
  • device_group - Optional - String - This is the group that you would like to register your device to. This group MUST exist at the dashboard under your project. Default value is Production.
  • software_version - Optional - String - This is the software version that is running on your device. This value will be displayed at the dashboard.

Response

The response will include a JSON with the key message.
  1. Success - status code is 200
    • The value of the message parameter is a JSON with the keys:
    • device_token - The value is String. This is your device token. Save that value for all future calls.

  2. Device is deleted - status code is 350
    • 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.

  3. Error
    • status code 400 - Check the value of the message key.
    • status code 429 - You have reached the limit of post requests per minute.

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

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.

URL: https://api.upswift.io/v1/agent/project_parameters
Request Type: GET
Payload Type: JSON

Request

  • device_token - Required - String - This is your device token. You have received this value in the response of the Register Device call.

Response

The response will include a JSON with the key message.
  1. Success - status code is 200
    • The value of the message parameter is a JSON with the keys:
    • status_timeout - The value is Integer. This is the timeout time between Device Status calls. (the value is in Seconds).

  2. Error
    • status code 400 - Check the value of the message key.
    • status code 429 - You have reached the limit of post requests per minute.

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

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 call).
This call represents a keep-alive message to Upswift servers, this way the server knows your device is online.

URL: https://api.upswift.io/v1/agent/device_status
Request Type: POST
Payload Type: JSON

Request

  • device_token - Required - String - This is your device token. You have received this value in the response of the Register Device call.
  • ram - Optional - Integer - This is your current device RAM usage (percentage). For example: a value of 30, will represent 30% RAM usage.
  • cpu - Optional - Integer - This is your current device CPU usage (percentage). For example: a value of 88, will represent 88% CPU usage.
  • disk_usage_total - Optional - 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 - Optional - Integer - This is your current usage of disk (MB). For example: a value of 182, will represent a current disk usage of 182MB.

Response

The response will include a JSON with the key message.
  1. Success - status code is 200
  2. New Project Parameters - status code is 301
    • 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.

  3. Remote Control connection is pending - status code is 302
    • Currently not in available

  4. New Micro-update is pending - status code is 300
    • Currently not in available

  5. New command is pending - status code is 309
    • Currently not in available

  6. Micro-update aborted - status code is 311
    • Currently not in available

  7. Error
    • status code 400 - Check the value of the message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'device_token': 'XXXXXXXXXXXXXXX',
                'ram': 33,
                'cpu': 12,
                'disk_usage_total': 1200,
                'disk_usage_current': 180}

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 == 300:
        ### UPDATE IS PENDING
    elif call_request.status_code == 301:
        ### NEW PROJECT PARAMETERS
    elif call_request.status_code == 302:
        ### REMOTE CONTROL IS PENDING
    elif call_request.status_code == 309:
        ### COMMAND IS PENDING
    elif call_request.status_code == 311:
        ### UPDATE IS ABORTED
    else:
        error = call_response["message"]
        print(error)