Difference between revisions of "Sensaphone.net API/device"

From Sensaphone.net
Jump to: navigation, search
(→‎Sensaphone.net API)
(→‎Specifications)
Line 34: Line 34:
 
}}{{TableRowN| device                | power_status        | String    | A device's power status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
 
}}{{TableRowN| device                | power_status        | String    | A device's power status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
 
}}{{TableRowN| device                | connection_status        | String    | A device's connection status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
 
}}{{TableRowN| device                | connection_status        | String    | A device's connection status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
 +
}}{{TableRowN| account          | feature              | Array of Object | The feature linked to the device (See [[Sensaphone.net API/feature]])              | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
}}{{TableEnd}}
 
}}{{TableEnd}}
  

Revision as of 10:07, 28 May 2015

Sensaphone.net API

Specifications

The device resource allows access to the devices that are bound to the account.

The device resource has the following properties:

Parent Property Property Type Description Create Delete Read Update
<parent> device Object The device object. ✓ ✓ ✓ n/a
device device_id Integer ID of the device. ✓
device id String Unique identifier located on the Device (Serial number, etc.) ✓
device name String Name of Device ✓ ✓
device description String Short description of Device ✓ ✓
device timezone String The timezone the Device is in ✓ ✓
device location Object Contains location information for the device. ✓ ✓
location address Object Address information for Device (See Sensaphone.net API/address) ✓ ✓
location coordinates Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates) ✓ ✓
device firmware String Firmware version of Device ✓ ✓
device default_schedule Object Alarm Schedule data (See Sensaphone.net API/alarmschedule) ✓ ✓
device device_schedule Object Alarm Schedule data (See Sensaphone.net API/alarmschedule) ✓ ✓
device zone Array of Objects Device Zone data (See Sensaphone.net API/zone) ✓ ✓
device offline_timeout Integer The number of minutes a device must be offline before it goes into alarm. ✓ ✓
device product String The name of the product type ✓
device modbus_ports Array of Objects TBD
device zone_meta Array of Objects TBD ✓
zone_meta zone Zone Meta Type TBD ✓
zone_meta children Array of Zone Meta Type TBD ✓
device is_offline_unack Boolean Whether or not an unacknowledged offline alarm exists. ✓
device is_online Boolean Whether or not the device is currently online. ✓
device standby_time String The number of minutes a device will be in standby mode. ✓ ✓
device standby_mode String A device's standby mode. ✓ ✓
device standby_status String A device's standby status ✓
device battery_status String A device's battery status ✓
device power_status String A device's power status ✓
device connection_status String A device's connection status ✓
account feature Array of Object The feature linked to the device (See Sensaphone.net API/feature) ✓ ✓


Zone Meta Type

PropertyType Description
zone_id Integer The Zone ID
is_enabled Integer Is the zone enabled
hide_if_disabled Boolean Hide the zone if disabled
add_name String The add name

GET

URI Mode Request URI's:

  • Receive all Device data for all Devices in a user's account
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device
  • Receive all Device data for a specific Device 
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}
  • Receive the alarm status of a Device 
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/status

JSON Mode Request URI: 

 POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "read"
  device Array of Objects The device object.

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  device Required Array of Objects The parent device object.
device device_id Optional Integer ID of Device
device id Optional Integer Unique identifier located on the Device (Serial number, etc.)
device name Optional String Name of Device
device description Optional String Short description of Device
device timezone Optional String The timezone the Device is in
device location Optional Object Contains location information for the device.
location address Optional Object Address information for Device (See Sensaphone.net API/address)
location coordinates Optional Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device firmware Optional String Firmware version of Device
device default_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device device_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device zone Optional Array of Objects Device Zone data (See Sensaphone.net API/zone)
device offline_timeout Optional Integer The number of minutes a device must be offline before it goes into alarm.
device product Optional String The name of the product type
device modbus_ports Optional Array of Objects TBD
device zone_meta Optional Array ofObjects TBD
zone_meta zone Optional Zone Meta Type TBD
zone_meta children Optional Array of Zone Meta Type TBD
device is_offline_unack Optional Boolean Whether or not an unacknowledged offline alarm exists.
device is_online Optional Boolean Whether or not the device is currently online.
device standby_time Optional String The number of minutes a device will be in standby mode.
device standby_mode Optional String A device's standby mode.
device standby_status Optional String A device's standby status
device battery_status Optional String A device's battery status
device power_status Optional String A device's power status
device battery_value Optional String A device's battery value
device power_value Optional String A device's power value
device connection_status Optional String A device's connection status
device feature Optional Array of Objects The feature linked to the account (See Sensaphone.net API/feature)
Example JSON

Receive all Device information for a specific Device

  • Request JSON:
{
  "acctid":987654,
  "session":"0123-4567-8901",
  "request_type":"read",
  "device": {
      "device_id":1234
     }
}


  • Response JSON:
{
  "result":
  {
    "success":true,
    "code":0,
    "message":"OK"
  },
  "response": 
  {
    "device":[
     {
       "device_id": 1234,
       ...
     }
    ]
  }      
}

PUT

URI Mode Request URI's:

  • Edit the description of a Device 
  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/description/{DESCRIPTION}
  • Edit the name of a Device 
  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/name/{DEVICE_NAME}

JSON Mode Request URI: 

  POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "update"
  device Array of Objects The device object.
device device_id Integer ID of the device.
device CHILD PROPERTY   Device's child properties to be edited*

*One or more device child properties below are required in addition to "device_id".

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  device Required Array of Objects The parent device object.
device device_id Optional Integer ID of Device
device name Optional String Name of Device
device description Optional String Short description of Device
device timezone Optional String The timezone the Device is in
device location Optional Object Contains location information for the device.
location address Optional Object Address information for Device (See Sensaphone.net API/address)
location coordinates Optional Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device firmware Optional String Firmware version of Device
device default_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device device_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device zone Optional Array of Objects Device Zone data (See Sensaphone.net API/zone)
device offline_timeout Optional Integer The number of minutes a device must be offline before it goes into alarm.
device modbus_ports Optional Array of Objects TBD
device standby_time Optional String The number of minutes a device will be in standby mode.
device standby_mode Optional String A device's standby mode.

POST

Adding a device

The preferred method to add a new Device is to use the JSON Mode Request. If the URI Mode Request is used you will be adding a Device with only the id value (not to be confused with the device_id), all other values will be left empty until a PUT request is used. With the JSON Mode Request you can add a Device with all values defined in one step.

URI Mode Request URI:

  • Add a new Device 
 POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/id/{DEVICEID}

JSON Mode Request URI: 

 POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "create"
  device Array of Objects The device object.
device id Integer Unique identifier located on the Device (Serial number, etc.)

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  device Required Array of Objects The parent device object.
device device_id Optional Integer ID of Device
device id Optional Integer Unique identifier located on the Device (Serial number, etc.)
device name Optional String Name of Device
device description Optional String Short description of Device
device location Optional Object Contains location information for the device.
location address Optional Object Address information for Device (See Sensaphone.net API/address)
location coordinates Optional Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device firmware Optional String Firmware version of Device
device default_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device device_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device zone Optional Array of Objects Device Zone data (See Sensaphone.net API/zone)
device offline_timeout Optional Integer The number of minutes a device must be offline before it goes into alarm.
device modbus_ports Optional Array of Objects TBD



Acknowledging Alarms

URI Mode Request URI:

  • Acknowledge All Alarms
 POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/acknowledge_all_alarms/{true}

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "create"
  device Array of Objects The device object.
device device_id Integer ID of Device
device ack_offline_alarm Boolean A write-only property that will acknowledge a device offline alarm
device acknowledge_all_alarms Boolean A write-only property that will acknowledge all alarms for a device, including all device alarms and all zone alarms

* "acknowledge_all_alarms" supersedes "ack_offline_alarm", if it is present in the request json other properties will be ignored

DELETE

URI Mode Request URI:

  • Delete a Device from an account 
 DELETE https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}

JSON Mode Request URI: 

 POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "delete"
  device Array of Objects The device object.
device device_id Integer ID of the device.
Retrieved from "https://wiki.sensaphone.net/index.php?title=Sensaphone.net_API/device&oldid=111"