dataprobe V230918W iBCS Restful API V4 URL Control User Guide
- June 13, 2024
- dataprobe
Table of Contents
iBCS Restful API V4
URL Control
V230918W
Overview
The iBoot-G2, iBoot-PoE and iBoot-PDU Family of products provides a simple
Restful API (URL Control) that allows users to control them easily from their
own websites and portals. This, however, requires the knowledge of the IP
Address of the iBoot(s) that need to be controlled. This is not always
practical.
Some internet connections do not provide static IP addresses making it
impossible to use the local Restful API. The iBoot Cloud Services (iBCS) is a
perfect solution to this problem.
iBoots make an outgoing connection to the iBCS for monitoring and control.
Since the iBCS does have a static IP address as well as a domain name, this
makes it the perfect solution to the aforementioned problem. This document
provides a specification for the first stage of the iBCS Restful API.
Restful API v4 Specifications
The addition of the ability to configure devices from the cloud is an iBCS
roadmap item. To this end Dataprobe released the iBoot-G2 Restful API v3.2 as
a starting point for iBCS G2 family configuration.
The Restful API known as Restful API v4 will include all the v3.2 features as
they existed and add some support for the configuration for the iBoot-PDU
series. The iBCS supports a Token based Restful API for controlling,
monitoring and configuring iBoot-G2 family devices. Version 4 will allow the
iBoot-PDU series to be programmed by utilizing the existing Token based API
and the command Line Interface (CLI) already built into the iBoot-PDU devices.
The Restful API v4 will include the following customer suggestions:
- The Restful API should be Token based.
- The Restful API should be able to get configuration data.
- The Restful API will allow use of the existing CLI command set in the PDU.
3.1. Token
An Authorized token is required for All Restful API communications. The token
is valid until a programmable amount of inactivity has elapsed. The inactivity
timer is programmable from 1 minute to 12 months. It can be programmed from
the Restful API or via the Web UI. All tokens can be revoked at any time
through the Restful API v4.
-
Authorization Tokens will be acquired from: https://iboot.co/services/v4/auth
Authorization Requests will use the following JSON Structure:
-
Authorization requests will respond with the following JSON structure:
3.2. Control
The iBCS Control Restful API will function as the same as current Control
Restful API. The only change will be to use an Authorization Token.
- Control will be accessed at: https://iboot.co/services/v4/control
- Control will use the following JSON structure:
- Control will respond with the following JSON structure:
3.3. Retrieve
The iBCS Retrieve Restful API functionality will allow users to retrieve
information on more than just one device at a time. Users can retrieve the
status of all the devices in their account, all the devices in a specification
location, or the status of just a specific type of device.
- Retrieve will be accessed at: https://iboot.co/services/v4/retrieve
- Retrieve will use one of the following the following JSON structures:
Retrieve All
This version of the Retrieve Command will Retrieve the status of all devices
in the account.
The user can optionally select all devices of a specific type.
Retrieve Location
This version of the Retrieve Command will Retrieve the status of all devices
in a selected location. The user can optionally select all devices of a
specific type.
Retrieve Specific
This version of the Retrieve Command will Retrieve the status of the device
with the selected MAC address.
Retrieve Response Format
- Retrieve will respond with the following structure for iBoot-G2/PoE:
- Retrieve will respond with the following structure for iBoot-G2+/G2S:
- Retrieve will respond with the following JSON structure for the iBoot-PDU:
3.4. Retrieve Shareable PDU Manage Link
The iBCS Retrieve Manage Link functionality will allow users to retrieve a
link that can be shared to log directly onto their iBoot-PDU series device as
if they had clicked on the Manage button available in the iBCS webpage. The
link will remain valid for 30 minutes, and if used for 30 minutes after
inactivity.
- Retrieve Shareable PDU Manage Link will be accessed at: https://iboot.co/services/v4/manage_link
- Retrieve Shareable PDU Manage Link will use the following the following JSON structure:
- Retrieve Shareable PDU Manage Link will respond with the following JSON structure:
3.5. Configuration Set – G2 Series
The Configuration Restful API v4 will take a variable number of items in the
JSON structures. This will allow for single variable changes. It will also
allow for variables from different setup pages to be sent in a single API
request. See Section 4 and 5 below for details regarding specific iBoot units.
-
All configuration set will be done through: https://iboot.co/services/v4/configuration/iBoot/set
-
The JSON structure will require at least 1 iBoot variable to configure.
-
The iBCS will save all variables in the database.
-
The iBCS will group the variables by product setting pages.
-
The iBCS will push all variables for each effected setup group.
-
The iBCS will push the data in HTTP Post format.
-
The configuration set request will use the following JSON structure:
JSON Objects: -
Command:
-
Response:
3.6. Configuration Get – G2 Series
The Configuration Restful API will be used to get the entire configuration or
any part thereof, of the selected iBoot. See Section 6 and 7 below for details
regarding specific iBoot units.
- All configurations get will be done through: https://iboot.co/services/v4/configuration/iBoot/get
- The configuration get request will use the following JSON structure:
- The configuration get request will respond with the following JSON structure:
3.7. Config Apply – G2 Series
The Configuration RestAPI will use this method (end point) to apply a selected
Configuration to a list of Selected Devices.
- All configurations get will be done through: https://iboot.co/services/v4/configuration/iBoot/apply
- The configuration apply command will use the following JSON structure:
- JSON Response
3.8. Shadow Database
It would be impractical for iBCS to process a get request by retrieving the
iBoot configuration directly from iBoot. To work around this the iBCS will use
a Shadow Database.
-
The Shadow Database will contain 1 variable for each setup pages of the iBoot-G2 family.
-
Each table will contain variable for all versions of the iBoot-G2 family.
-
Each table will start as blank until
1. The iBoot sends its setting to cloud via Commit Long Poll.
▪ After a reboot or settings change saved on webpage
2. The Configuration Set Restful API is used. -
The Restful API Set will apply factory defaults to all unset variables.
iBoot-G2 Configuration Set
4.1. Device Configuration Set
The following is used to POST JSON structure that will make changes to the
iBoot-G2 units Device settings.
https://iboot.co/services/v4/configuration/iBoot/set
Note: If the Location is changed a reboot is required.
4.2. Network Configuration Set
4.3. Advanced Network Configuration Set
4.4. Autoping Configuration Set
4.5. Schedule Configuration Set
4.6. Reboot
iBoot-G2+/S Configuration Set
The following is used to POST JSON structure that will make changes to the
iBoot-G2P or iBoot-G2S
Device settings. https://iboot.co/services/v4/configuration/iBoot/set
Note: If the Location is changed a reboot is required.
5.1. Device Configuration Set
5.2.
Expansion Configuration Set
5.3.
Network Configuration Set
5.4. Advanced Network Configuration Set
5.5. Graceful Shutdown Configuration Set
5.6. Autoping Configuration
Set
5.7. Heartbeat Configuration
Set
5.8. Schedule Configuration
Set
5.9. Reboot
This JSON structure is used to reboot the iBoot-G2. It has the same effect
pressing the reset button on the iBoot-G2.
iBoot-G2 Configuration Get
The Restful API Configuration get is a mechanism where users can request
current device configuration data from iBCS.
The following is used to POST JSON structure that will retrieve current
configuration of iBoot-G2 Device settings from iBCS.
https://iboot.co/services/v4/configuration/iBoot/get
Upon posting the JSON structure above to iBCS, iBCS will
return the current configuration for specified tables list. The response to
the Restful API configuration get will be as follows: [sample data shown]
6.1. Device Configuration Get
6.2. Network Configuration Get
6.3. Advanced Network Configuration Get
6.4. Autoping Configuration Get
6.5. Schedule Configuration Get
iBoot-G2+/S Configuration Get
The Restful API Configuration get is a mechanism where users can request
current device configuration data from iBCS.
The following is used to POST JSON structure that will retrieve current
configuration of iBoot-G2+ and G2S Device settings from iBCS.
https://iboot.co/services/v4/configuration/iBoot/get
Upon posting the JSON structure above to iBCS, iBCS will
return the current configuration for specified tables list. The response to
the Restful API configuration get will be as follows: [sample data shown]
7.1. Device Configuration Get
7.2. Expansion Configuration Get
7.3. Network Configuration Get
7.4. Advanced Network Configuration Get
7.5. Graceful Shutdown
Configuration Get
7.6. Autoping
Configuration Get
7.7.
Heartbeat Configuration Get 7.8. Schedule Configuration Get
iBoot-PDU Configuration Set
8.1. Device Configuration Set
The following is used to POST JSON structure that will send iBoot-PDU CLI set
commands to the iBootPDU to program the settings in the iBoot-PDU that the CLI
would.
https://iboot.co/services/v4/configuration/pdu/set
- Command:
- Response:
iBoot-PDU Device Configuration set quick example:
8.2. Device Configuration Get
The following is used to POST JSON structure that will send iBoot-PDU CLI get
commands to the iBootPDU to retrieve the settings from the iBoot-PDU that the
CLI would.
https://iboot.co/services/v4/configuration/pdu/get
- Command:
- Response:
iBoot-PDU Device Configuration get quick example:
Examples
Below are some examples of iBoot-G2 family control, retrieve, configure get
and configure set via Restful API v4.
9.1. Retrieve Token
To retrieve a valid token from the iBCS via the API for use with all
subsequent API commands.
The username and password are for the iBoot.co account. Sample will retrieve a
token valid for 20 minutes of inactivity using account name MyDemoUser and
password Password123. [as per section 3.1] curl -d
‘{“username”:”MyDemoUser”,”password”:”Password123″,”timeout”:{“interval”:”20″,”scale”:”minutes”}}’
-X
POST https://iboot.co/services/v4/auth
The command above will return a JSON structure as following:
{“success”:”true”,”token”:”e3ec-e4f6-910f-ac38″}
9.2. iBoot-G2/PoE Control Example
To control an iBoot-G2/PoE to Cycle via RestFul API: [as per section 3.2] curl
-d ‘{“token”:”####-####-####-####”,”mac”:”00-0d-
ad-01-02-03″,”outlet”:”0″,”control”:”cycle”}’ -X POST
https://iboot.co/services/v4/control
The command above will return a JSON structure as following:
{“success”:”true”,”message”:”Sent ‘cycle’ to 00-0d-ad-01-02-03 outlets (0)”}
9.3. iBoot Retrieve All Example
To query status of all devices in the account via RestFul API: [as per
Retrieve All section 3.3] curl -d ‘{“token”:”####-####-####-####”,”all”:[“”]}’
-X POST https://iboot.co/services/v4/retrieve
The command above will return a JSON structure based on all units In account
similar to following:
{“success”:”true”,”message”:null,”devices”:[{“mac”:”00-0d-
ad-01-02-03″,”name”:”iBoot-G2-010203″, “online”:true,”location”:”on
Desk”,”lastContact”:”2023-04-17 18:04:54″,
“ip”:”192.168.1.205″,”status”:{“Main”:”ON”,”AP-1″:”Inactive”,”AP-2″:”Inactive”},”triggerInfo”:{“APT1″:”0”},
{“mac”:”00-0d-ad-0a-0b-
0c”,”name”:”iBoot-G2-0a0b0c”,”online”:false,”location”:”at
Home”,”lastContact”:”2023-01-12 10:02:32″,
“ip”:”192.168.1.205″,”status”:{“Main”:”ON”,”AP-1″:”Inactive”,”AP-2″:”Inactive”},
“triggerInfo”:{“APT1″:”0”}}]}
9.4. iBoot-G2 Retrieve Specific Example
To query an iBoot-G2/PoE status via RestFul API: [as per Retrieve Specific
section 3.3] curl -d ‘{“token”:”####-####-####-####”,”mac”:”00-0d-
ad-01-02-03″}’ -X POST https://iboot.co/services/v4/retrieve
The command above will return a JSON structure as following:
{“success”:”true”,”message”:null,”devices”:[{“mac”:”00-0d-
ad-01-02-03″,”name”:”iBoot-G2010203″,”online”:true,”location”:”on
Desk”,”lastContact”:”2023-04-14 18:04:54″,
“ip”:”192.168.1.254″,”status”:{“Main”:”ON”,”AP-1″:”Inactive”,”AP-2″:”Inactive”},”triggerInfo”:{“APT1″:”0”}}]}
9.5. iBoot-PDU Retrieve Shareable Manage Link
The iBoot-PDU series allows a Manage button from within the iBCS interface.
The API will allow retrieval of an identical functioning link that can be
shared. The link will expire after 30 minutes if not used and will expire
after 30 minutes of inactivity if it is used. [as per section 3.4] curl -d
‘{“token”:”####-####-####-####”,”mac”:”a8-e7-7d-01-02-03″}’ -X POST
https://iboot.co/services/v4/manage_link
The command above will return a JSON structure as following:
{“success”:”true”,”message”:”https://########.device.iboot.co”}
9.6. iBoot-G2 Configure Set Example
To Configure Device setting of an iBoot-G2: This sample sends to a specific
iBoot by its mac address [as per section 3.5] curl -d
“{“token”:”####-####-####-####”,”mac”:”00-0d-
ad-01-02-03″,”device”:{“location”:”iBoot-G2-010203″,
“cycleTime”:”10″,”disableOff”:”0″,”initialState”:”last”,”upgradeEnable”:”0″,”autoLogout”:”60″}}”
-X POST
https://iboot.co/services/v4/configuration/iBoot/set
The command above will return a JSON structure as following:
{“success”:”true”,”message”:{“0″:”Sent
‘location=iBoot-G2-010203&cycle=10&iMain=2&aLog=60’ to device Old-G2 name (00
-0d-ad-01-02-03)”}}
9.7. iBoot-G2 Configure Get Example
To Retrieve Device configuration of iBoot-G2 via Restful API: This sample
requests the device and network settings of a specific iBoot-G2. [as per
section 3.6] curl -d ‘{“token”:”####-####-####-####”,”mac”:”00-0d-
ad-01-02-03″,”tables”:[“device”,”network”]}’ –X POST
https://iboot.co/services/v4/configuration/iBoot/get
The command above will return a JSON structure as following:
{“success”:”true”,”device”:{“location”:”iBoot-G2010203″,”cycleTime”:10,”disableOff”:0,”initialState”:”last”,”upgradeEnable”:0,”autoLogout”:60},”network”:{“ipMode”:”static”,”ipAddress”:”192.168.1.254″,”subnetMask”:”255.255.255.0″,”gateway”:”192.168.1
.1″,”dns”:”192.168.1.1″}}
9.8. iBoot-G2+/S Control Example
To control an iBoot-G2+/S to Cycle all 3 outlets via RestFul API: [as per
section 3.2] curl -d ‘{“token”:”####-####-####-####”,”mac”:”00-0d-
ad-01-02-03″,”outlet”:[“0″,”1”,”2”],”control”:”cycle”}’ -X POST
https://iboot.co/services/v4/control
The command above will return a JSON structure as following:
{“success”:”true”,”message”:”Sent ‘cycle’ to 00-0d-ad-01-02-03 outlets (0, 1,
2)”}
9.9. iBoot-G2+/S Retrieve Specific Example
To query an iBoot-G2+ or iBoot-G2S status via RestFul API: [as per Retrieve
Specific section 3.3] curl -d ‘{“token”:”####-####-####-####”,”mac”:”00-0d-
ad-01-02-03″}’ -X POST https://iboot.co/services/v4/retrieve
The command above will return a JSON structure as following:
{“success”:”true”,”message”:null,”devices”:[{“mac”:”00-0d-ad-01-02-03″,”name
”:”iBoot-G2S-010203″, “online”:true,”location”:”at
Home”,”lastContact”:”2023-04-15 20:35:04″,
“ip”:”192.168.1.208″,”status”:{“Main”:”ON”,”EXP-1″:”ON”,”EXP-2″:”ON”,”Main-2″:”ON”,”Input-1″:”Open”,”Input2″:”Open”,”Output-1″:”Closed”,”Output-2″:”Closed
”,”AP-1A”:”Inactive”,”AP-
1B”:”Inactive”,”AP-2″:”Inactive”,”AP3″:”Inactive”,”HB”:”Inactive”},”triggerInfo”:{“APT1″:”0″,”APT2″:”0″,”APT3″:”0″,”HBT1″:”0”}}]}
9.10. iBoot-G2+/S Configure Set Example
To Configure Schedule setting of iBoot-G2+ or iBoot-G2S via Restful API:
Sample sets a specific iBoot-G2S unit, event 1 as 4/24/2023 to cycle Main at
10:05, repeating Daily. [as per section 5.8] curl -d
“{“token”:”####-####-####-####”,”mac”:”00-0d-ad-01-02-03″,
“schedule”:{“date1″:”04/24/2023″,”time1″:”10:05″,”repeat1″:”1″,”repeatPeriod1″:”days”,”action1″:”cycle”,”outlet1″:”
Main”,”enable1″:”1″}}” -X POST
https://iboot.co/services/v4/configuration/iBoot/set
The command above will return a JSON structure as following:
Even though setting only 1 event all events are part of the reply.
{“success”:”true”,”message”:{“0″:”Sent
‘date1=04/24/2023&time1=10:05&rt1=1&rep1=0&act1=2&ctl1=0&run1=&date2=&date3=&date4=&date5=&date6=&date7=&date8=&time2=&time3=&time4=&time5=&time6=&time7=&time8=&rt2=0&rt3=0&rt4=0&rt5=0&rt6=0&rt7=0&rt8=
0&rep2=0&rep3=0&rep4=0&rep5=0&rep6=0&rep7=0&rep8=0&act2=0&act3=0&act4=0&act5=0&act6=0&act7=0&act8=0&run2=&run3=&run4=&run5=&run6=&run7=&run8=&date9=&dateA=&dateB=&dateC=&dateD=&dateE=&time9=&time
A=&timeB=&timeC=&timeD=&timeE=&rt9=0&rtA=0&rtB=0&rtC=0&rtD=0&rtE=0&rep9=0&repA=0&repB=0&repC=0&repD=0&repE=0&act9=0&actA=0&actB=0&actC=0&actD=0&actE=0&run9=&runA=&runB=&runC=&runD=&runE=&ctl2=0&ctl
3=0&ctl4=0&ctl5=0&ctl6=0&ctl7=0&ctl8=0&ctl9=0&ctlA=0&ctlB=0&ctlC=0&ctlD=0&ctlE=0&clr2=Clear&clr3=Clear&clr4=C
lear&clr5=Clear&clr6=Clear&clr7=Clear&clr8=Clear&clr9=Clear&clrA=Clear&clrB=Clear&clrC=Clear&clrD=Clear&clrE=Clear
‘ to device iBoot-G2S-010203 (00-0d-ad-01-02-03)”}}
9.11. iBoot-PDU Control Example
To control all outlets of the iBoot-PDU via RestFul API: [as per section 3.2]
curl -d
‘{“token”:”####-####-####-####”,”mac”:”a8-e7-7d-01-02-03″,”outlet”:[“0″,”1″,”2″,”3″,”4″,”5″,”6″,”7”],
“control”:”cycle”}’ -X POST
https://iboot.co/services/v4/control
The command above will return a JSON structure as following:
{“success”:”true”,”message”:”Sent ‘cycle’ to a8-e7-7d-01-02-03 outlets (0, 1,
2,3,4,5,6,7)”}
9.12. iBoot G2 series Reboot Example
To force reboot of the iBoot (G2, PoE, G2S or G2+) via RestFul API: [as per
section 4.6 and 5.9] curl -d ‘{“token”:”####-####-####-####”,”mac”:”00-0d-
ad-01-02-03″,”reboot”:”1″}’ -X POST
https://iboot.co/services/v4/control
The command above will return a JSON structure as following:
{“success”:”true”,”message”:”Sent ‘reboot=’ to 00-0d-ad-01-02-03″}
9.13. iBoot-PDU Retrieve Specific Example
To query an iBoot-PDU status via RestFul API: [as per Retrieve Specific
section 3.3] curl -d
‘{“token”:”####-####-####-####”,”mac”:”a8-e7-7d-01-02-03″}’ -X POST
https://iboot.co/services/v4/retrieve
The command above will return a JSON structure as following:
{“success”:”true”,”message”:null,”devices”:[{“mac”:”a8-e7-7d-01-02-03″,
“name”:”MainControlUnit”,”online”:true,”location”:”at
Home”,”lastContact”:”2023-04-15
09:47:17″,”ip”:”0.0.0.0″,”status”:[{“Server”:”On”},{“Router”:”On”},{“Outlet-3″:”On”},{“Outlet-4″:”On”},{“Outlet5″:”On”},{“Outlet-6″:”On”},{“Outlet-7″:”Off”},{“Outlet-8″:”Off”}],”triggerInfo”:[]}]}
9.14. iBoot-PDU v4 set command Example
The following sample will add and configure a sequence named Wall to Schedule
outlet 4 to go off, wait 10 seconds then turn outlet 4 back on and then create
an autoping to ping google.com every 30 seconds with failure count of 4 and a
restart time of 60 seconds. The autoping will run the sequence Wall when it
fails.
Please note the 25 commands are a repeat of what it would take to program the
same sequence and autoping using the CLI if connected to the unit CLI
interface.
curl -d “{“token”:”####-####-####-####”,”mac”:”00-0d-ad-01-02-03″,
“commands”:[ “add sequence Wall”,”add sequence Wall action”,”add sequence Wall
action”,”add sequence Wall action”,”set sequence Wall action 1 type
outlet”,”set sequence Wall action 1 param1 localhost”,”set sequence Wall
action 1 param2 4″,”set sequence Wall action 1 param3 OFF”,”set sequence Wall
action 2 type delay”,”set sequence Wall action 2 param1 10″,”set sequence Wall
action 3 type outlet”,”set sequence Wall action 3 param1 localhost”,”set
sequence Wall action 3 param2 4″,”set sequence Wall action 3 param3 ON”,”set
sequence Wall enabled true”,”set user admin sequence Wall yes”,”add autoping
Wall”,”set autoping Wall address google.com”,”set autoping Wall period
30″,”set autoping Wall count 4″,”set autoping Wall timeout 2″,”set autoping
Wall restartdelay 60″,”set autoping Wall failtriggersequence Wall”,”set
autoping Wall cleartriggersequence none”,”set autoping Wall enabled true”]}”
-X POST https://iboot.co/services/v4/configuration/pdu/set
The command above will return a JSON structure as following:
{“success”:”true”,”message”:”add sequence Wall\n\nOk\nadd sequence Wall
action\n\nOk\nadd sequence Wall action\n\nOk\nadd sequence Wall
action\n\nOk\nset sequence Wall action 1 type outlet\n\nOk\nset sequence Wall
action 1 param1 localhost\n\nOk\nset sequence Wall action 1 param2
4\n\nOk\nset sequence Wall action 1 param3 OFF\n\nOk\nset sequence Wall action
2 type delay\n\nOk\nset sequence Wall action 2 param1 10\n\nOk\nset sequence
Wall action 3 type outlet\n\nOk\nset sequence Wall action 3 param1
localhost\n\nOk\nset sequence Wall action 3 param2 4\n\nOk\nset sequence Wall
action 3 param3 ON\n\nOk\nset sequence Wall enabled true\n\nOk\nset user admin
sequence Wall yes\n\nOk\nadd autoping Wall\n\nOk\nset autoping Wall address
google.com\n\nOk\nset autoping Wall period 30\n\nOk\nset autoping Wall count
4\n\nOk\nset autoping Wall timeout 2\n\nOk\nset autoping Wall restartdelay
60\n\nOk\nset autoping Wall failtriggersequence Wall\n\nOk\nset autoping Wall
cleartriggersequence none\n\nOk\nset autoping Wall enabled true\n\nOk”}
Dataprobe Inc Technical Support
60E Commerce Way
Totowa New Jersey 07512
www.dataprobe.com/support
support@dataprobe.com
201-934-9944
201-934-5111
iBCS Restful API v4
V230918W
References
- Dataprobe Cloud Service - Beta Login
- mywebsite.com is available for purchase - Sedo.com
- iboot.co/services/v4/auth
- iboot.co/services/v4/configuration/iBoot/apply
- iboot.co/services/v4/configuration/iBoot/get
- iboot.co/services/v4/configuration/iBoot/set
- iboot.co/services/v4/configuration/pdu/get
- iboot.co/services/v4/configuration/pdu/set
- iboot.co/services/v4/control
- iboot.co/services/v4/manage_link
- iboot.co/services/v4/retrieve