API

1. Overview

This document describes the API exposed by the WE500. The API is based on the exchange of XML documents over HTTP following, as much as possible, the REST principles.

The API exposes the following types of resources:

  • API key
  • Variables
  • Group of variables

The main purpose of the API is to make possible the creation, modification and deletion of such resources. In general these operation are mapped to HTTP methods.

The API is based on resources. Each resource is reachable through an URL and, depending on the HTTP method used, the server will accomplish the desired request. The HTTP verbs supported by the API are:

  • GET : get an XML document that describe the requested resource
  • POST : create a new resource
  • PUT : modify a resource
  • DELETE : delete a resource
  • OPTIONS : get a list of supported HTTP methods
  • HEAD : same as GET but doesn’t give a response

The last two methods are implemented for all the resources and they are not specified in the following chapters.

The WE500 will respond to every request received with an HTTP that contains one of the following HTTP status codes:

Status code Description
200 OK The request to create a new resource has been satisfied.
201 Created The request to create a new resource has been satisfied.
400 Bad request The request doesn’t meet this specification.
401 Unauthorized The client hasn’t sufficient privileges.
404 Not found The resource doesn’t exists.
405 Method Not Allowed The HTTP method used is not supported for requested resource.
409 Conflict The request is in conflict with the current resources. For example, if a resource is created twice, the second time it will give this conflict error.
500 Internal Server Error An error occurred in the server side.

All requests require the user to have specific privileges. The API supports two methods to specify clients identity:

  • HTTP Basic Authentication
  • Provide an API key in the request

In particular the API key can be inserted in the query string using api_key as name, or with the following snippet of XML code:

<ntx>
    <authentication>
        <api_key>1234</api_key>
    </authentication>
</ntx>

Note that the HTTP GET method doesn’t allow the attachment of documents in the request, so in this case the API key in the query string must be provided.

Hint

Nethix strongly recommends to use the HTTPS protocol when communicating with the WE500

2. Resources

2.1 API key

An API key is a token that is used to identify a client. This resource must always be called before calling any another resource, otherwise the client won’t be authorized to access the desired resource. During a session, the first call to this resource needs to send the user’s login and password. The response, if the credentials were correct, will be the API that will be used for the subsequent calls. For security reasons, each session will have different API keys.

URL

/api/v1/api_key?login=###&passwd=###

login : the username of a user of WE500

passwd : the password of a user of WE500

GET

Response:

<ntx>
    <authentication>
        <api_key>2oChQKxdveMIB0tR4pdVSHqmpvmaVnMs</api_key>
    </authentication>
</ntx>

POST

Not allowed.

PUT

Not allowed.

DELETE

Not allowed.

2.2 Variables

A variable contains the current status of a parameter of the monitoring system. For example, a variable called Temperature could contain the value of an analog temperature sensor attached to the WE500.

The response contains not only the current value of the measured parameter, but also its previous value, if an alarm is active and the characteristics of the variable that depend on its type. For example, An analog input returns it’s maximum/minimum values, measurement unit and number of decimals.

URL

/api/v1/variable/(id;)*(?_byname=TRUE)?

  • Id : list of variable ids separated by semicolon. If not present the resource is all the variables
  • _byname : if present and it’s value is TRUE then the ids are treated as variable names

GET

In this example, the response contains data for three variables called Temperature (analog input), Overfill (digital input) and Pump (digital output).

Response:

<ntx>
    <variables>
        <variable>
            <ctrl_id>180</ctrl_id>
            <protocol>0</protocol>
            <name>Temperature</name>
            <analog_input>
            <phys_id>1</phys_id>
            <min>0.0</min>
            <max>1000.0</max>
            <units>ooo</units>
            <decimals>1</decimals>
            </analog_input>
            <status>
                <value>1.0</value>
                <value_prev>1.0</value_prev>
                <alarm_active>0</alarm_active>
                <alarm_visible/>
            </status>
        </variable>
        <variable>
            <ctrl_id>181</ctrl_id>
            <protocol>1</protocol>
            <name>Overfill</name>
            <digital_input>
            <phys_id>1</phys_id>
            <active_label>yes</active_label>
            <inactive_label>no</inactive_label>
            <mode>0</mode>
            <cnt_init/>
            <cnt_end/>
            <cnt_inc/>
            <units/>
            <impulse_cnt_scale/>
            <edge/>
            <invert_led>0</invert_led>
            </digital_input>
            <status>
                <value>no</value>
                <value_prev>yes</value_prev>
                <alarm_active>0</alarm_active>
                <alarm_visible/>
            </status>
        </variable>
        <variable>
            <ctrl_id>187</ctrl_id>
            <protocol>2</protocol>
            <name>Pump</name>
            <digital_output>
            <phys_id>1</phys_id>
            <type>0</type>
            <active_label>on</active_label>
            <inactive_label>off</inactive_label>
            <delay>0</delay>
            <pulse_duration/>
            </digital_output>
            <status>
                <value>off</value>
                <value_prev>off</value_prev>
                <alarm_active>0</alarm_active>
                <alarm_visible/>
            </status>
        </variable>
    </variables>
</ntx>

XML tags

  • protocol: It’s the type of variable.
    • 0 : Analog input
    • 1 : Digital input
    • 2 : Digital output
    • 3 : Modbus
    • 4 : Virtual (WE500 internal)

POST

Not allowed.

PUT

Not allowed.

DELETE

Not allowed.

2.3 Variables status

This method allows to set or get the current status (or value) of a variable. When getting the status of a variable, this method returns only the <status> part of the previous resource variable leaving aside its characteristics. The variable can specified by its id or its name.

URL

/api/v1/variable/status/(id;)*(?_byname=TRUE)?

  • id : list of variable ids separated by semicolon. If not present, all the variables are returned.
  • _byname : if present and it’s value is TRUE, the ids are treated as variable names

GET

In this example, the response return the current value, previous value and if there is an alarm on variables with ids 180, 181 and 187.

Response:

<ntx>
<variables>
    <variable>
        <ctrl_id>180</ctrl_id>
        <status>
            <value>1.0</value>
            <value_prev>1.0</value_prev>
            <alarm_active>0</alarm_active>
            <alarm_visible/>
        </status>
    </variable>
    <variable>
        <ctrl_id>181</ctrl_id>
        <status>
            <value>no</value>
            <value_prev>yes</value_prev>
            <alarm_active>0</alarm_active>
            <alarm_visible/>
        </status>
    </variable>
    <variable>
        <ctrl_id>187</ctrl_id>
        <status>
            <value>off</value>
            <value_prev>off</value_prev>
            <alarm_active>0</alarm_active>
            <alarm_visible/>
        </status>
    </variable>
</variables>
</ntx>

POST

Not allowed.

PUT

Change the current value of one variable. This method can be applied in the following cases:

  • Reset a digital input counter or digital input time counter variable. The value to be set is 0.
  • Open or close a digital output variable. The value to be set corresponds to the active or inactive labels of the variable.
  • Set a write-only or read-write modbus variable. If the variable is a 1 bit size variable, the value to be set corresponds to the active or inactive labels of the variable.

For example, if a digital output has the label off for turning-off a pump, the URL of the request will contain the id of the variable and the payload of the request will have the following content:

Request:

<ntx>
    <value>off</value>
</ntx>

DELETE

Not allowed.

2.4 Groups of variables

A set of variables that are associated as a single unit or group. It is useful for obtaining the ids of several variables using just one method, instead of calling one method per variable.

This method also allows to create, modify or delete a group.

URL

/api/v1/variable_group/(id;)

  • id : list of groups of variables ids separated by semicolon. If not present, all the groups of variables are returned.

GET

In this example, the response returns all the variables ids that belong to the groups of variables with id 11 and 13.

Response:

<ntx>
    <variable_groups>
        <variable_group>
            <id>11</id>
            <name>Sensors</name>
            <variables>
                <variable><ctrl_id>196</ctrl_id></variable>
                <variable><ctrl_id>197</ctrl_id></variable>
                <variable><ctrl_id>198</ctrl_id></variable>
                <variable><ctrl_id>199</ctrl_id></variable>
                <variable><ctrl_id>200</ctrl_id></variable>
                <variable><ctrl_id>201</ctrl_id></variable>
                <variable><ctrl_id>202</ctrl_id></variable>
                <variable><ctrl_id>203</ctrl_id></variable>
            </variables>
        </variable_group>
        <variable_group>
            <id>13</id>
            <name>Actuators</name>
            <variables>
                <variable><ctrl_id>231</ctrl_id></variable>
                <variable><ctrl_id>232</ctrl_id></variable>
                <variable><ctrl_id>233</ctrl_id></variable>
            </variables>
        </variable_group>
    </variable_groups>
</ntx>

POST

Create a new empty group of variables.

Request:

<ntx>
    <variable_group>
        <name>New sensors</name>
    </variable_group>
</ntx>

PUT

Modify the name of a group of variables.

Request:

<ntx>
    <variable_group>
        <name>New sensors</name>
    </variable_group>
</ntx>

DELETE

Delete one or more groups of variables. The group id must be specified in the URL. No parameters are required.

2.5 Group of variables membership

This method allows to add or remove one or more variables to/from a group of variables.

URL

/api/v1/variable_group/(gid)/variable/(vid;)+

  • gid : id of a group of variables
  • vid : one or more variable ids

GET

Not allowed.

POST Not allowed.

PUT

Add one or more variables to a group of variables. No XML payload is required.

DELETE

Remove one or more variables from a group of variables. No XML payload is required.

3. Examples

This section shows some examples of how to use the API.

3.1 Filling a water tank

Suppose that the WE500 is controlling how a water tank is being filled.

The first operation is to obtain an API key through the API key method:

Request:

GET http://we500/api/v1/api_key?login=admin&passwd=nethix

Resonse:

<ntx>
    <authentication>
        <api_key>1ce9bd6cb98042313e249268787753dc3ecc8136</api_key>
    </authentication>
</ntx>

Now all the information about the two variables of the WE500 that we are interested in can be get using the Variables method.

Request:

GET http://we500/api/v1/variable/Filling_pump;Water_level?api_key=1ce9bd6cb98042313e249268787753dc3ecc8136&_byname=TRUE

Response:

<ntx>
    <variables>
        <variable>
            <ctrl_id>7</ctrl_id>
            <protocol>0</protocol>
            <name>Water_level</name>
            <send_portal>0</send_portal>
            <analog_input>
                <phys_id>1</phys_id>
                <min>0.0</min>
                <max>100.0</max>
                <units>Liter</units>
                <decimals>0</decimals>
            </analog_input>
            <status>
                <value>23</value>
                <value_prev>23</value_prev>
                <alarm_active>0</alarm_active>
                <alarm_visible/>
            </status>
        </variable>
        <variable>
            <ctrl_id>9</ctrl_id>
            <protocol>2</protocol>
            <name>Filling_pump</name>
            <send_portal>0</send_portal>
            <digital_output>
                <phys_id>1</phys_id>
                <type>0</type>
                <active_label>Stop</active_label>
                <inactive_label>Start</inactive_label>
                <delay>0</delay>
                <pulse_duration/>
            </digital_output>
            <status>
                <value>Stop</value>
                <value_prev>Stop</value_prev>
                <alarm_active>0</alarm_active>
                <alarm_visible/>
            </status>
        </variable>
    </variables>
</ntx>

From the response obtained it can be seen that the following:

There is an analog input variable named Water_level with id 7 that informs that there are 23 liters in the water tank.

There is also a digital output variable named Filling_pump used for powering on/off the pump and at the moment is stopped.

Now the pump can be powered on using the Variables status method:

Request:

PUT http://we500/api/v1/variable/status/9:

<ntx>
    <authentication>
        <api_key>1ce9bd6cb98042313e249268787753dc3ecc8136</api_key>
    </authentication>
    <value>Start</value>
</ntx>

Now that the pump is filling the tank, the water level can be read periodically using again the Variables status method:

Request:

GET http://we500/api/v1/variable/status/7?api_key=1ce9bd6cb98042313e249268787753dc3ecc8136

Response:

<ntx>
    <variables>
        <variable>
            <ctrl_id>7</ctrl_id>
            <status>
                <value>30</value>
                <value_prev>29</value_prev>
                <alarm_active>0</alarm_active>
                <alarm_visible></alarm_visible>
            </status>
        </variable>
    </variables>
</ntx>

And when the tank is full, the pump can be stop using again the Variables status method:

Request:

PUT https://we500/api/v1/variable/status/9:

<ntx>
    <authentication>
        <api_key>1ce9bd6cb98042313e249268787753dc3ecc8136</api_key>
    </authentication>
    <value>Start</value>
</ntx>