dataprobe V230918W iBCS Restful API V4 URL Control User Guide

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

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>