Power Alert Device Manger (v20)

REST API User’s Guide

 

Introduction

Beginning with version 20.0.0, PowerAlert Device Manager (PADM) supports a Representational State Transfer (REST) Application Programming Interface (API). This specification document defines the REST APIs, including the Uniform Resource Identifier (URI), method, parameters, request body and response body. These specifications are intended to provide all required details to call the PowerAlert REST APIs and to build scripts around these calls.

Supported REST API Version

 

PowerAlert Release

Rest API Version

20.0

1.0.0

 

The API version should be entered in the 'Accept-Version' header, as shown in the image below. If the version is not entered, the server returns the latest supported version. Third party systems that consume the PowerAlert API should provide the expected version in this header.

 

Client Request

GET https://{poweralert_endpoint}/api/devices   
Authorization: Bearer {access_token}
Content-Type: application/vnd.api+json
Accept-Version: 1.0.0

 

Guidelines

Authentication and Authorization

·       Authentication and Authorization of the PowerAlert API is based on the OAuth2.0 standard and uses a JSON Web Token (JWT)

·       A successful authentication request returns a valid access token

·       In all cases, a valid access token is required to interact with the PowerAlert API

·       Refer to the Authentication Model section of this document for additional details

Validation and Constraints

As shown below, an API response for a GET request has “meta” and “data” parts. The “meta” part consists of validation and constraints; the “data” part contains a response attribute in the form of key value pairs. Validation provides information about the data attribute (e.g. minimum and maximum), whereas constraints indicate whether a data attribute is required and can be edited or deleted. Refer to Appendix B for a detailed explanation of metadata.

 

{
        "meta": {
                 "id": "6a85a9a9-7f7a-4538-941c-c33dbacb3077",
                 "constraints": {
                         "max_items": 0,
                         "min_items": 0,
                         "editable_attributes": [
                                 "name",
                                 "location",
                         ],
                         "required_attributes": [],
                         "delete_allowed": true
                 },
                 "validation": [
                         {
                                 "attribute": "name",
                                 "maximum": 0,
                                 "minimum": 0,
                                 "default": 0,
                                 "multiple_of": 0,
                                 "min_length": 1,
                                 "max_length": 64,
                                 "pattern": "",
                                 "enum": [],
                                 "type": "string"
                         },
                         {
                                 "attribute": "location",
                                 "maximum": 0,
                                 "minimum": 0,
                                 "default": 0,
                                 "multiple_of": 0,
                                 "min_length": 1,
                                 "max_length": 80,
                                 "pattern": "",
                                 "enum": [],
                                 "type": "string"
                         }
                 ]
        },
        "data": {
                 "type": "devices",
                 "id": "1",
                 "attributes": {
                         "name": "device-123",
                         "manufacturer": "TRIPP LITE",
                         "location": "chicago"
                 }
        }
}

Validations and constraints may be omitted by turning the validation flag to false. e.g:  /api/email-contacts?validation=false

Required Attributes

Required attributes are needed when adding objects (POST requests). A list of required attributes for a specific endpoint are listed in the “meta” section of the GET response. In the example below, the “meta” section of the  GET /api/ localusers response lists the required attributes (shown in bold).

{
    "meta": {
        "id": "f760f23e-175d-4704-b81d-e37e5e34566b",
        "constraints": {
        
            "editable_attributes": [
               
            ],
            "required_attributes": [
                "name",
                "password",
                "role",
                "session_timeout_enabled",
                "idle_timeout_enabled"
            ],
            "delete_allowed": true
        },
        "validation": [
               ..]
        ...
       }
}           

Each update (PATCH) request supports partial updates in which case all the fields are not required. Only the values specified in the request body are updated; missing fields are omitted, retaining their values.

Content Type

Clients must send all requests with the following header: 

Content-Type: application/vnd.api+json

The server responses also include this header.

API Unique Identifier

A unique identifier is required to create, read, update and/or delete an individual item. This identifier can either be ID or name. If using name as the identifier, then he following custom HTTP header is required to access data by name.

 

By: name

 

 

Authentication Model

Authentication Endpoint

PowerAlert uses the OAuth 2.0 token-based authentication model. Under this model, a user calls POST /api/outh/token to request an access token. A token is returned if the credential (user name and password) in the POST request is valid. The token appears in the headers of each subsequent request and determines if the user is authorized to perform the operation. The access token must be included in the HTTP header of subsequent requests.  For details see section Authentication (Login & Logout).

 

 

Authentication Request

POST https://{poweralert_endpoint}//api/oauth/token
Content-Type: application/vnd.api+json
Accept-Version: 1.0.0
{
    "username":"localadmin",
    "password":"localadmin",
    "grant_type": "password"
}              

 

Authentication Response

 

On receiving a valid request, the server returns an access token and refresh token with a “successful” HTTP Error Code response:

 

Status: 200 OK

 

Refer to Appendix A for information on HTTP Error Codes.

{
    "access_token": "eyJ0eXoiVElNRUZPUk1BVF9ITU1TU1RUIiwiaWRsZV90aW1lb3V0Ijo2MCwic2Vzc2lvbl90aW1lb3V0IjozNlsibG9nX2ZpbGVzOnIiLCJzc2xfdXBsb2FkOnJ3Iiwic3NsX2Rvd25sb2FkOnIiLCJhcGk6cnciLCJlYnBfdXBsb2FkOnJ3Il19fQ.8fKhR3Rkk5AlVS3i4QosTlqXlx5TdX5uD9FN7w1p-9k",
    "msg": "Logged in as localadmin",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MjMxNTY4OTksIm5iZiI6MTYyMzE1Njg5OSwianRpIjoiNjY2NzBmMWQtYzg2Ny00YzA4LWE1ZTQtMTQ1YjI2MjY1ZDExIiwiZXhwIjoxNjIzMTc4NDk5LCJpZGVudGl0eSI6ImxvY2FsYWRtaW4iLCJ0eXP3dHyMyqo41ur0NvZ9QveWNxu4Q"
}                     

 

Accessing Other APIs

 

To interact with PowerAlert API, a valid access token generated from a successful authentication response must be entered in the HTTP header. In the example below -- getting device information from PowerAlert – the token is entered in place of {access_token}. The IP address or host name is entered in place of {poweralert_endpoint}.

 

GET https://{poweralert_endpoint}/api/devices/1 
Authorization: Bearer {access_token}
Content-Type: application/vnd.api+json
Accept-Version: 1.0.0

 

Refresh Token

 

The refresh token helps to acquire a new access token when the existing one expires. Use the /api/oauth/refresh endpoint to refresh the access token. For the API to work, the refresh token must be included in the Authorization header.

 

Refresh Token Request:

POST https://{poweralert_endpoint}/api/oauth/refresh 
Authorization: Bearer {refresh_token}
Content-Type: application/vnd.api+json
Accept-Version: 1.0.0

 

Refresh Token Response:

Status: 200 OK
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXlRJTUVGT1JNQVRfREVGQVVMVCIsImlkbGVfdGltZW91dCI6NjAsInNlc3Npb25fdGltZW91dCI6MzYwLCJwcml2aWxlZ2VzIjpbImxvZ19maWxlczpyIiwic3NsX3dyJdfX0.tuhFpE7XD4uZqsEUn1pL9wQB5Ne0bIJYYXv5nTHNIy4"
}

 

Logging Out

 

To Log Out, issue a logout API request to invalidate the existing access token.

 

Logout Request:

 

POST https://{poweralert_endpoint}/api/oauth/token/logout 
Authorization: Bearer {refresh_token}
Content-Type: application/vnd.api+json
Accept-Version: 1.0.0

 

Logout Response:

 

Status: 200 OK
{"msg":"Refresh token has been revoked"}

 

Examples

A number of basic examples are provided in this section; refer to the following link for additional examples.

https://documenter.getpostman.com/view/447714/TzeUn8vX

 

The following two variables are used throughout the examples:

·       {{DevEndpointHttps}} – This represents the HTTP(S) endpoint of a device, for example: http://10.22.0.98

·       {{access_token}} – This access token is required for interacting with the PowerAlert API Refer to the Authentication Model section of this document for details on obtaining this access token.

 

Device Properties

This section provides API examples on how to retireve and update attributes of a PowerAlert device and any peripherals connected to it.  Some attributes, such as “Device Name”, “Location”, “Installation Data” and “Asset Identifier” can be edited using device update service (PATCH /api/device/id).

 

Retrieving Device Properties

 

The example below retrieves all properties of the PowerAlert device and any connected peripherals. Specify the port if it different from the default values of 80 for HTTP or 443 for HTTPS.

 

Device Properties Request:

 

curl --location -g --request GET '{{DevEndpointHttps}}/api/devices' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept-Version: 1.0.0' \
--data-raw ''     
 

Device Properties Response:

 

Status: 200 OK

 

{
        "meta": {
               "id": "a0dd05e8-729e-4a20-907d-ef4994731226",
               "constraints": {
                       "max_items": 0,
                       "min_items": 0,
                       "editable_attributes": [
                               ...
                               
                       ],
                       "required_attributes": [],
                       "delete_allowed": true
               },
               "validation": [{
                  ..
               }
               ]
        },
        "data": [{
                       "type": "devices",
                       "id": "1",
                       "attributes": {
                               "device_id": 1,
                               "name": "Device0391",
                               "manufacturer": "TRIPP LITE",
                               "model": "SMART1500RM2U",
                               "serial_number": "2850DY0SM820600391",
                               "protocol": "3015",
                               "location": "Chicago",
                               "port_mode": "DEVICE_COMM_RS232",
                               "port_name": "/dev/ttyS2",
                               "region": "Mid West",
                               "install_date": "2021-05-17",
                               "deactivate_date": ""
                         ...
                       }
               },
               {
                       "type": "devices",
                       "id": "2",
                       "attributes": {
                               "device_id": 2,
                               "name": "Sensor0473",
                               "manufacturer": "TRIPP LITE",
                               "model": "E2MTHDI ",
                               "serial_number": "2833AV0AC89FC00473",
                               "protocol": "9300",
                               "location": "",
                               "port_mode": "DEVICE_COMM_RS232",
                               "port_name": "/dev/serial/by-id/usb-TRIPP_LITE_TRIPP_LITE_E2MTHDI_2833AV0AC89FC00473-if00",
                               "region": "",
                               "install_date": "2021-05-17",
                               "deactivate_date": "2021-05-21"
                         ....
                       }
               }
        ]
}

 

·       This example shows only a portion of the response; the device has many more attributes.

·       Use device id or name “/api/devices/{id}” to retrieve the attributes of one device.

·       Use the following HTTP header to retrieve attributes by device name

 

By: name

 

Retrieving a Device’s Properties by ID:

 

curl --location -g --request GET '{{DevEndpointHttps}}/api/devices/{DeviceId}' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept-Version: 1.0.0' \
--data-raw '' 

 

Retrieving a Device’s Properties by name:

 

curl --location -g --request GET '{{DevEndpointHttps}}/api/devices/{DeviceName}' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept-Version: 1.0.0' \
--header 'By: name' \
--data-raw ''  
 

 

 

Updating Editable Device Properties

 

Note that device ID or device name is required to edit attributes.

 

Device Update Request by ID:

 

curl --location -g --request PATCH '{{DevEndpointHttps}}/api/devices/{deviceId}' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept-Version: 1.0.0' \
--data-raw '{
               "data": {
                       "type": "devices",
                       "attributes": {
                       "id": "1",
                       "name": "Device0391",
                       "location": "Chicago",
                       "manufacturer": "TRIPP LITE",
                       "installDate": "2021-05-18",
                       "region": "USA",
                       "configured_device_id": 123,
                       "configured_asset_tag": "tripplitelight-0123456",
                       "install_date": "2021-05-18"
                       }
               }
         }'

·       The following attributes are editable: name, location, manufacturer, location, region, configured_device_id and configured_asset_tag.

·       Similar to GET, the device ID must be specified when requesting updates. Alternatively the device name can be used along with the following Http cusom header.

By: name

 

Device Update Request by name:

 

curl --location -g --request PATCH '{{DevEndpointHttps}}/api/devices/Device0391' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept-Version: 1.0.0' \
--header 'By: name' \
--data-raw '{
               "data": {
                       "type": "devices",
                       "attributes": {
                       "id": "1",
                       "name": "Device0391",
                       "location": "Chicago",
                       "manufacturer": "TRIPP LITE",
                       "installDate": "2021-05-18",
                       "region": "USA",
                       "configured_device_id": 123,
                       "configured_asset_tag": "tripplitelight-0123456",
                       "install_date": "2021-05-18"
                       }
               }
         }'

 

Device Update Response:

 

Status: 200 OK

 

{
        "meta": {
               "id": "c143e284-a1b3-4d64-ad72-64092e3dfac8"
        },
        "data": {
               "type": "devices",
               "id": "1",
               "attributes": {
                       "response": 0
               }
        }
}

 

Device Metrics       

This section provides API examples for retrieving devices metrics (variables), including:

·       Runtime Remaining

·       Battery Voltage

·       Battery Capacity

·       Input and Output Voltage / Current

·       Input and Output Frequency

·       Output Utilization

·       Temperature

 

Metrics can be retrieved as a full set or by individual variable

 

Retrieving All Device Metrics

 

Device Metrics Request:

 

curl --location -g --request GET '{{DevEndpointHttps}}/api/variables' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept-Version: 1.0.0' \    
--data-raw ''
 

 

Device Metrics (Variables) Response:

{
        "meta": {
               "id": "a0dd05e8-729e-4a20-907d-ef4994731226",
               "constraints": {
                       "max_items": 0,
                       "min_items": 0,
                       "editable_attributes": [
                               ...            
                       ],
                       "required_attributes": [],
                       "delete_allowed": true
               },
               "validation": [{
                  ..
               }
               ]
        },
        "data": [{
                       "type": "variables",
                       "id": "1",
                       "attributes": {
                               "key": 872415338,
                               "device_id": 1,
                               "device_name": "Device0391",
                               "device_type": "DEVICE_TYPE_UPS",
                               "label": "Runtime Remaining (Min)",
                               "value": "474",
                               "min_value": 0,
                               "max_value": 1440,
                               "suffix": "Minutes",
                               "group": "VARGROUP_BATTERY",
                               "purpose": "VARPURPOSE_STATUS",
                               "data_type": "VARTYPE_INTEGER",
                               "state": "DEVICE_STATE_NORMAL",
                               "display_label": "Runtime Remaining",
                               "raw_value": "474",    
                               ....
                       }
               },
               {
                       "type": "variables",
                       "id": "2",
                       "attributes": {
                               "key": 872415360,
                               "device_id": 1,
                               "device_name": "Device0391",
                               "device_type": "DEVICE_TYPE_UPS",
                               "label": "Battery Capacity",
                               "value": "100",
                               "min_value": 0,
                               "max_value": 100,
                               "suffix": "%",
                               "group": "VARGROUP_BATTERY",
                               "purpose": "VARPURPOSE_STATUS",
                               "data_type": "VARTYPE_INTEGER",
                               "state": "DEVICE_STATE_NORMAL",
                               "display_label": "Battery Capacity",
                               "raw_value": "100",
                         ....
                       }
               },
               ...             
        ]
}

 

·       This example shows only a portion of the response; the device has many more variables.

·       This response shows all variables for the PowerAlert device and connected peripherals – Each variable has a device ID, type and details

·       Attribute “label” is the variable name, “value” is the value of the variable and “suffix” is the unit of measure.

 

Retrieving Individual Device Metrics

 

Request Using ID:

curl --location -g --request GET '{{DevEndpointHttps}}/api/variables/{variableId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept-Version: 1.0.0' \
--data-raw ''
 

Where {variableId} is the device metric ID or variable ID

 

Retrieve a variable using its ID:

https://10.22.0.58/api/variables/7

 

 A variable can also be retrieved using its name in which case the following values must be included in the HTTP header.

·       “By : name”

·       “deviceId : {id}” or “deviceName: {name}” – Where id is the unique ID of the device and name is the name of the device 

 

Request Using Name:

 

curl --location -g --request GET '{{DevEndpointHttps}}/api/variables/{variableName}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'By: name' \
--header 'deviceName: Device0391' \
--header 'Accept-Version: 1.0.0' \
--data-raw ''

 

Where {variableName} is device metric name or variable name

 

Example: https://10.22.0.98/api/variables/Runtime Remaining (Min)

 

Response:

 

Status: 200 OK

 

{
        "meta": {
               "id": "a0dd05e8-729e-4a20-907d-ef4994731226",
               "constraints": {
                       "max_items": 0,
                       "min_items": 0,
                       "editable_attributes": [
                               ...            
                       ],
                       "required_attributes": [],
                       "delete_allowed": true
               },
               "validation": [{
                  ..
               }
               ]
        },
        "data": {
               "type": "variables",
               "id": "1",
               "attributes": {
                       "key": 872415338,
                       "device_id": 1,
                       "device_name": "Device0391",
                       "device_type": "DEVICE_TYPE_UPS",
                       "label": "Runtime Remaining (Min)",
                       "value": "474",
                       "min_value": 0,
                       "max_value": 1440,
                       "suffix": "Minutes",
                       "group": "VARGROUP_BATTERY",
                       "purpose": "VARPURPOSE_STATUS",
                       "data_type": "VARTYPE_INTEGER",
                       "state": "DEVICE_STATE_NORMAL",
                       "display_label": "Runtime Remaining",
                       "raw_value": "474",    
                         ....
               }
        }
}

API Reference

All PowerAlert REST APIs leverage HTTP Status Codes to indicate errors and successful responses. Refer to Appendix A for details.

Actions

Action APIs enable configuration of action parameters applicable to the device and connected peripherals. Below are examples of configurable action parameters, followed by the supported enumerations (enums):

·       Delay – the number of seconds the action will wait to execute after being triggered

·       Target Device – the device undergoing the action

·       Interval – the number of seconds between successive executions of the action

·       Count – the number of times the action will be executed

·       Contacts – one or more notification/trap/set recipients

·       Action Type – the type of action; each has an enumeration value

·       Trigger Event – the trigger for the action, occurring either when the event is set (On Set) or cleared (On Clear). These events contains additional attributes pertaining to the event (device, load, etc). 

 

source_type:

EVENT_SOURCE_TYPE_DEVICE
EVENT_SOURCE_TYPE_AUTOPROBE
EVENT_SOURCE_TYPE_SYSTEM

 

action_type:

ACTIONTYPE_REBOOT_WEBLX

ACTIONTYPE_TURN_OFF_DEVICE

ACTIONTYPE_TURN_ON_DEVICE

ACTIONTYPE_SENSOR

ACTIONTYPE_EMAIL

ACTIONTYPE_SNMP_SET_OID

ACTIONTYPE_SNMP_TRAP

ACTIONTYPE_SMS

ACTIONTYPE_LOAD

ACTIONTYPE_LOAD_GROUP

ACTIONTYPE_RAMP

ACTIONTYPE_SHED

ACTIONTYPE_EXEC_SCRIPT

ACTIONTYPE_SHUTDOWN_OS

ACTIONTYPE_REBOOT_OS

ACTIONTYPE_REMOTE_SHUTDOWN

ACTIONTYPE_RESTART_DEVICE

 

 

GET All Actions

This API returns a summary of all available actions.

 

Title

GET All Actions                                                                                                

URL

/api/actions

Method

GET

Success Response

Code: 200
Content: {

    "meta": {

        "id": "837e874a-507e-4061-b6f9-f6835e977e9e",

        "constraints": {

                   ..

        },

        "validation": [

           …

        ]

    },

    "data": [

        {

            "type": "actions",

            "id": "1",

            "attributes": {

                "name": "Default Email Notification", //String ValueAction Name

                "action_type": "ACTIONTYPE_EMAIL", //ActionType ENUM

                "key": 1281,// <Intger value>

                "delay": 30, //Delay integer value

                "interval": 0,// Integer Value

                "count": 1, // Integer Value

                "enabled": true,

                "redundant": false,

                "set_events": 25, // Integer Value

                "clear_events": 25 // Integer Value           }

        }

  ]

}

Sample Call

 
curl –i -H "Accept: application/vnd.api+json"

http://localhost:3001/api/actions

Version 

"Accept-Version: 1.0.0" – If no version provided, the service return the latest one

 

Delete Action

This API deletes an action, based on action ID or action name

 

Title

Delete Action                                                                                               

URL

/api/actions/:actionId

OR

To delete using name: /api/actions/:actionName 

"by:name" http header is required to delete by name

Method

DELETE

Success Response

Code: 200
Content: {

    "meta": {

        "id": "b3039324-3961-4188-b6b1-649daf7794fb"

    },

    "data": {

        "type": "actions",

        "id": 0,

        "attributes": {

            "response": 0

        }

    }

}

Sample Call

 
curl –I -H "Accept: application/vnd.api+json" –X "DELETE”

http://localhost:3001/api/actions/7

Version 

"Accept-Version: 1.0.0" – If no version provided, the service return the latest one

 

Delete Multiple Actions

This API deletes multiple actions based on the action IDs provided in the body

 

Title

Delete Multiple Actions

URL

/api/actions

Method

DELETE

Data Params

{

       "data": [{

             "type": "actions",

             "id": "9" //Integer Action ID

       }, {

             "type": "actions",

             "id": "10"

       }]

}

Success Response

Code: 200
Content: {

    "meta": {

        "id": "bf1c99d8-d8c4-4fbf-8cb7-eb9facdde7c3" //Request Id

    },

    "data": [

        {

            "type": "actions",

            "id": "9" //Integer action Id

        },

        {

            "type": "actions",

            "id": "10"

        }

    ]

}

Version 

"Accept-Version: 1.0.0"

                       

 

GET Supported Actions

This API provides the Boolean value for each of the action types, indicating support for on_set, on_clear and mutually_exclusive. If mutually_exclusive is set to true, either on_set or on_clear can be supported, but not both.

 

Title

GET Supported Actions

URL

/api/actions/supported

Method

GET

Success Response

Code: 200
Content: {

       "meta": {

             "id": "1d20d459-83a4-4168-8aa9-debfbcc6e6a5"

       },

       "data": {

             "type": "actions-supported",

             "id": "ActionsSupported",

             "attributes": {

                    "email_supported": {

                          "supported_on_set": true, //Boolean

                          "supported_on_clear": true, //Boolean

                          "mutually_exclusive": false //Boolean

                    },

                    "sms_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": true,

                          "mutually_exclusive": false

                    },

                    "snmp_trap_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": true,

                          "mutually_exclusive": false

                    },

                    "snmp_set_oid_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": true,

                          "mutually_exclusive": true

                    },

                    "reboot_webcardlx_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": false,

                          "mutually_exclusive": false

                    },

                    "turn_off_device_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": true,

                          "mutually_exclusive": false,

                          "devices": [{

                                 "id": 1,

                                 "name": "Device0391"

                          }]

                    },

                    "turn_on_device_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": true,

                          "mutually_exclusive": false,

                          "devices": [{

                                 "id": 1, //Integer

                                 "name": "Device0391" //String

                          }]

                    },

                    "reboot_os_supported": {

                          "supported_on_set": false,

                           "supported_on_clear": false,

                          "mutually_exclusive": false

                    },

                    "sensor_supported": {

                          "supported_on_set": false,

                          "supported_on_clear": false,

                          "mutually_exclusive": false,

                          "devices": []

                    },

                    "ramp_supported": {

                          "supported_on_set": false,

                          "supported_on_clear": true,

                          "mutually_exclusive": false,

                          "devices": [{

                                 "id": 1,

                                 "name": "Device0391"

                          }]

                    },

                    "shed_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": false,

                          "mutually_exclusive": false,

                          "devices": [{

                                 "id": 1,

                                 "name": "Device0391"

                          }]

                    },

                    "load_action_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": true,

                          "mutually_exclusive": true,

                           //Load identifier for deviev

                          "load_identity_per_device": [{

                                 "device": {

                                       "id": 1, //Integer device Id

                                       "name": "Device0391"

                                 },

                                 "loads": [{

                                              "id": "1", //Integer load id

                                              "name": "Load number 1",//String load number

                                              "load_number": 1 //Integer

                                       },

                                       {

                                              "id": "2",

                                              "name": "Load 2",

                                              "load_number": 2

                                       }

                                 ]

                          }]

                    },

                    "load_group_action_supported": {

                          "supported_on_set": false,

                          "supported_on_clear": false,

                          "mutually_exclusive": true,

                           "load_group_identity_per_device": []

                    },

                    "remote_shutdown_supported": {

                          "supported_on_set": false,

                          "supported_on_clear": false,

                          "mutually_exclusive": false

                    },

                    "mute_alarm_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": false,

                          "mutually_exclusive": false,

                          "devices": [{

                                 "id": 1,

                                 "name": "Device0391"

                          }]

                    },

                    "initiate_self_test_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": false,

                          "mutually_exclusive": false,

                          "devices": [{

                                 "id": 1,

                                 "name": "Device0391"

                          }]

                    },

                    "restart_device_supported": {

                          "supported_on_set": true,

                          "supported_on_clear": false,

                          "mutually_exclusive": false,

                          "devices": [{

                                 "id": 1,

                                 "name": "Device0391",// String device name

                                 "parameters": {

                                       "Cmd Turn On Device (Delayed) Data": "Seconds"

                                 }

                          }]

                    }

             }

       }

}

Version 

"Accept-Version: 1.0.0"

 

 

Email Action

 

The Email Action endpoint provides a Create, Read, Update, Delete (CRUD) API for email actions.  Email Action has attributes ‘email_contact’ and ‘send_to_all’. If attribute ‘send_to_all’ is set to true, the email will be sent to all email contacts. If set to false, the ‘email_contact’ field must contain one or more valid email contact IDs.

 

GET Email Action

 

Title

GET Email action                                                                                                

URL

/api/email_actions

Method

GET

URL Params

Get Email Action

/api/email_actions/:actionId - By id (default)

or

/api/email_actions/:actionName

Note: No HTTP header required to get email action by id

http header "by: name" required to get email action by name

Success Response

Code: 200
Content {

    "meta": {

        "id": "92b2d8f3-49d2-4ae3-916e-70e0a6af8549",

        "constraints": {

           …

        },

        "validation": [

           …

        ]

    },

    "data": {

        "type": "email_actions",

        "id": "11",

        "attributes": {

            "name": "email_action",

            "key": 0,

            "delay": 0,

            "enabled": true,

            "trigger_events": [

                {

                    "id": "5",

                    "key": 0,

                    "name": "",

                    //ENUM EventSourceTYpe

                    "source_type": "EVENT_SOURCE_TYPE_DEVICE",

                    "source_id": 1, //Integer is

                    "source_name": "Device0391",

                    "action_id": "11",//Integer action id

                    "action_name": "",

                    "fire_on_set": false,

                    "fire_on_clear": true

                }

            ],

            "interval": 0,

            "count": 1,

            "send_to_all": true,

            "email_contact": []

        }

    }

}

Sample Call

 
curl –i -H "Accept: application/vnd.api+json" 
http://localhost:3001/api/email_actions/11

Version 

"Accept-Version: 1.0.0" – If no version provided, the service return the latest one

 

 

Create Email Action

 

Title

Create Email Action

URL

/api/email_actions

Method

POST

Data Params

{

       "data": {

             "type": "email_actions",

             "attributes": {

                    "name": "Email Action",

                    "interval": 0,

                    "delay": 0,

                    "count": 1,

                    "enabled": true,

                    "key": 0,

                    "send_to_all": true,

                    "trigger_events": [{

                          "id": "5",

                          "name": "Overload",

                          "fire_on_set": true,

                          "fire_on_clear": false,

                          "action_name": "Email Action",

                           //ENUM – EventSourceType

                          "source_type": "EVENT_SOURCE_TYPE_DEVICE",

                          "source_id": 1,

                          "source_name": "Device0391",

                          "key": 0

                    }]

             }

       }

}

Success Response

Code: 200
Content: {

       "meta": {

             "id": "50771da9-a56b-43ca-a324-0c95f0104c99"

       },

       "data": {

             "type": "email_actions",

             "id": "8", //Integer – Action ID

             "attributes": {

                    "response": 0

             }

       }

}

Version 

"Accept-Version: 1.0.0" – If no version provided, the service return the latest one

 

 

Update Email Action

 

Title

Update Email Action

URL

/api/email_actions

Method

PATCH

URL Params

PATCH Email Action

/api/email_actions/:actionId - By id (default)

or

/api/email_actions/:actionName

Note: No HTTP header required to get email action by id

http header "by: name" required to update email action by name

Data Params

{

       "data": {

             "type": "email_actions",

             "attributes": {

                    "name": "Email Action2",//String Value

                    "interval": 0, //Intger Value

                    "delay": 0, //Intger Value

                    "count": 1, //Intger Value

                    "enabled": true,

                    "key": 0, //Intger Value

                    "send_to_all": true,

                    "trigger_events": [{

                          "id": "5", //Intger Value

                          "name": "Overload",//String Value

                          "fire_on_set": true,

                          "fire_on_clear": false,

                          "action_name": "Email Action",

                          "source_type": "EVENT_SOURCE_TYPE_DEVICE",//Enum Event Source

                          "source_id": 1, //Intger Value

                          "source_name": "Device0391", //String Value

                          "key": 0 //Intger Value

                    }]

             }

       }

}

Success Response

Code: 200
Content: {

       "meta": {

              "id": "50771da9-a56b-43ca-a324-0c95f0104c99"

       },

       "data": {

             "type": "email_actions",

             "id": "8",

             "attributes": {

                    "response": 0

             }

       }

}

Version 

"Accept-Version: 1.0.0" – If no version provided, the service return the latest one

NOTE

The payload for update is similar to create. Alternatively update api allow to add and remove list of email contacts, set and clear events. Example:

 …

    "remove_set_events" : [

          {

            "name" : "seteventname2",

            "source_type": "EVENT_SOURCE_TYPE_DEVICE",

            "source_name" : "sourcename2"

          }

        ],

        "add_email_contact" : [

          {

            "name" : "contact1"

          },

          {

            "name" : "contact2"

          }

        ],

        "add_clear_events" : [

          {

            "name" : "cleareventname1",

            "source_type": "EVENT_SOURCE_TYPE_DEVICE",

            "source_name" : "sourcename1"

          }

        ],

        "add_set_events" : [

          {

            "name" : "seteventname1",

            "source_type": "EVENT_SOURCE_TYPE_DEVICE",

            "source_name" : "sourcename1"

          }

        ],

        "remove_email_contact" : [

          {

            "name" : "contact3"

          },

          {

            "name" : "contact4"

          }

        ],

        "remove_clear_events" : [

          {

            "name" : "cleareventname2",

            "source_type": "EVENT_SOURCE_TYPE_DEVICE",

            "source_name" : "sourcename1"

          }

...

 

Initiate Self-Test Action

 

The Initiate Self-Test Action endpoint provides a CRUD API for Initiate Self-Test actions. It requires a target device identity in the form of ‘device_name’ or ‘device_id’.

 

GET Initiate Self-Test Action

 

Title

GET Initiate Self-Test Action

URL

/api/initiate_self_test_actions

Method

GET

URL Params

Get Initiate Self-Test Actions

/api/initiate_self_test_actions/:actionId

- By id (default)

or

/api/initiate_self_test_actions/:actionName

Note: No HTTP header required to get action by id

http header "by: name" required to get action by name

Success Response

Code: 200
Content {

    "meta": {

        "id": "92b2d8f3-49d2-4ae3-916e-70e0a6af8549",

        "constraints": {

           …

        },

        "validation": [

           …

        ]

    },

    "data": {

        "type": "email_actions",

        "id": "11",

        "attributes": {

         "name": "anInitiateSelfTestActionName",

         "key": 0,

         "delay": 0,

         "enabled": true,

         "trigger_events": [         {

            "id": "1",

            "key": 0,

            "name": "",

            //ENUM – EventSourceType

            "source_type": "EVENT_SOURCE_TYPE_DEVICE",

            "source_id": 1,

            "source_name": "",

            "action_id": "20",

            "action_name": "",

            "fire_on_set": true,

            "fire_on_clear": true

         }],

         "device_identity":          {

            "device_id": 1,

            "device_name": ""

        }

    }

}

Version 

"Accept-Version: 1.0.0" – If no version provided, the service return the latest one

 

 

Create an Initiate Self-Test Action

 

Title

Create Initiate Self-Test Action

URL

/api/initiate_self_test_actions

Method

POST