API

1. Introduction

This section is useful for users that want to establish a communication between the portal and other platforms such as billing systems or data analysis for predictive behavior.

It’s also useful for developing mobile apps that interact with the portal without the need to connect directly to the single devices.

2. API overview

This document describes the API exposed by Nethix servers. It’s 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
  • Customer
  • Domain
  • Device
  • Variable
  • Portal log

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 accomplishes the desired request. The HTTP methods 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 server 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 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 client to have some 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 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.

3. API Resources

3.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 client’s login and password. The response, if the credentials were correct, will be the API key that will be used for the subsequent calls.

For security reasons, each session will have different API keys.

URL

/api/v1/api_key

GET

Parameters

If a valid API key in not provided or HTTP Basic Auth is not used, the following parameters must be provided:

  • login
  • password

Response

<ntx>
    <authentication>
        <api_key>6sBtnYrMhgEehQuY1LA6TRYVArj3YfRI</api_key>
    </authentication>
</ntx>
POST
Not allowed.
PUT
Not allowed.
DELETE
Not allowed.

3.2. Customer

Represents the customer of the client making the request.

URL

/api/v1/customer

GET

Response

<ntx>
  <customer>
    <name>Nethix S.r.l.</name>
    <domains>
      <domain>
        <id>1</id>
        <name>Water control station</name>
      </domain>
      <domain>
        <id>2</id>
        <name>Radio station</name>
      </domain>
    </domains>
  </customer>
</ntx>
POST
Not allowed.
PUT
Not allowed.
DELETE
Not allowed.

3.3. Domain

Represent a collection of devices.

URL

/api/v1/domain(/(id;)*)?

If no domain ids are specified the URL will address all the domains.

GET

Response

<ntx>
  <domains>
    <domain>
      <id>1</id>
      <name>Water control station</name>
      <vpn_enable>1</vpn_enable>
      <devices>
        <device>
          <id>4</id>
          <name>Water tank 1</name>
        </device>
        <device>
          <id>5</id>
          <name>Water tank 2</name>
        </device>
      </devices>
    </domain>
  </domains>
</ntx>
POST
Not allowed.
PUT
Not allowed.
DELETE
Not allowed.

XML Tags

  • vpn_enable - 1 if the domain VPN is enable, 0 otherwise

3.4. Device

A physical Nethix device (i.e. WE500).

URL

/api/v1/device(/(id;)*)?

If no device ids are not specified the URL will address all the devices.

GET

Response

<ntx>
  <devices>
    <device>
      <id>4</id>
      <name>Water tank 1</name>
      <type>1</type>
      <last_ip>201713153</last_ip>
      <domain>
        <id>1</id>
      </domain>
      <data_delivery_enable>1</data_delivery_enable>
      <remote_access_enable>1</remote_access_enable>
      <serial_number>0ac59f00000097</serial_number>
      <latitude> 45.682608988</latitude>
      <longitude> 4.7153341770</longitude>
      <variables>
        <variable>
          <id>3</id>
          <name>Water_level</name>
        </variable>
        <variable>
          <id>4</id>
          <name>Water_temperture</name>
        </variable>
        <variable>
          <id>5</id>
          <name>Filling_pump</name>
        </variable>
      </variables>
    </device>
  </devices>
</ntx>
POST
Not allowed.
PUT
Not allowed.
DELETE
Not allowed.

XML Tags

  • type - the device type, possible values are
    • 1 - WE500
    • 2 - PC
  • last_ip - integer representation of the last received IP address from the device

3.5. Variable

A device variable that was sent to the server at least one time.

URL

/api/v1/variable(/(variable_id;)*)?

If no device id are specified the URL will address all the variables.

GET

Response

<ntx>
  <variables>
    <variable>
      <id>3</id>
      <name>Water_level</name>
      <access_mode>0</access_mode>
      <protocol>0</protocol>
      <active_label/>
      <inactive_label/>
      <size>0</size>
      <device>
        <id>4</id>
      </device>
    </variable>
  </variables>
</ntx>
POST
Not allowed.
PUT
Not allowed.
DELETE
Not allowed.

XML Tags

  • access_mode -
    • 0 - Read only
    • 1 - Write only
    • 2 - Read-write
  • protocol -
    • 0 - Analog input
    • 1 - Digital input
    • 2 - Digital output
    • 3 - Modbus
    • 4 - Virtual variable
  • active_label- Value to show when the value is 1
  • inactive_label - Value to show when the value is 0
  • size - The number of bits that compose the variable (meaningful only for modbus variables)

3.6. Portal log

A portal log is simple a set of variables and their values at a specific point in time.

URL

/api/v1/device/device_id/portal_log(/(variable_id;)*)?

If no variable ids are specified the URL will address all the portal logs of the device with id equal to device_id.

GET

Parameters

This method accepts the following parameters in order to refine the results:

  • from_ts - Start time. It is a UNIX timestamp
  • to_ts - End time. It is a UNIX timestamp
  • limit - The maximum number of portal logs in the response

Response

<ntx>
  <portal_logs>
    <variables>
      <timezone_shift>120</timezone_shift>
      <timestamp>1401253621</timestamp>
      <variable>
        <id>3</id>
        <name>Water_level</name>
        <value>30</value>
      </variable>
      <variable>
        <id>4</id>
        <name>Water_temperture</name>
        <value>20</value>
      </variable>
    </variables>
    <variables>
      <timezone_shift>120</timezone_shift>
      <timestamp>1401253681</timestamp>
      <variable>
        <id>3</id>
        <name>Water_level</name>
        <value>29</value>
      </variable>
      <variable>
        <id>4</id>
        <name>Water_temperture</name>
        <value>20</value>
      </variable>
    </variables>
  </portal_logs>
</ntx>

3.7. VPN

Request VPN status/data for connecting to the VPN.

This resource is used by the WE500 for getting the necessary data to establish a VPN connection to the Portal. It is useful for the customers that need the WE500 to establish a VPN connection to a server that is not the Nethix Portal.

URL
/api/v1/vpn

GET

Response

<ntx>
    <vpn>
        <reconnection_time>10</reconnection_time>
        <status>2</status>
        <package_info>
            <auth_type>0</auth_type>
            <md5_ca_cert>422d6be13d96ebbe44a710eca79bbbff</md5_ca_cert>
            <md5_client_conf>d41d8cd98f00b204e9800998ecf8427e</md5_client_conf>
            <md5_ta_key>6d05e5f3bab43672a6189c3e1cf05d17</md5_ta_key>
            <md5_credentials>05t5f69ca672a6189c3e1cf05dab5</md5_credentials>
        </package_info>
    </vpn>
</ntx>
POST
Not allowed.
PUT
Modify the status of the VPN.
Request
At the moment the devices can only use this method to change the VPN status from update client configuration (3) to enable (2).
<ntx>
    <vpn>
        <status>2</status>
    </vpn>
</ntx>
DELETE
Not alowed.

XML Tags

  • recconnection_time - when the VPN is not enabled, the client should wait this time (in seconds) before querying the VPN status again.

  • status - VPN status, possible values are:
    • 1 : Disable
    • 2 : Enable
    • 3 : Update client configuration

    When the status is disable, the response does not have the package_info tag.

  • auth_type - VPN client authentication mechanism, possible values are:
    • 0 : Login and password

  • md5_ca_cert - The MD5 of ca.crt

  • md5_client_conf - The MD5 of client.ovpn

  • md5_ta_key - The MD5 of ta.key

  • md5_credentials - The MD5 of credentials.txt

The previous files are transmitted in a single compressed file and checked against these checksums.

More information on how the WE500 uses a VPN can be found in the WE500 VPN section.

3.8. VPN Packet

Download the VPN files needed for establishing a VPN connection.

This resource is used only after the WE500 received an Update client configuration status reply in the previous resource 3.7. VPN. It is useful if the WE500 needs to establish a VPN connection to a server that is not the Nethix Portal.

URL
/api/v1/vpn/packet

GET

Response

Return the VPN files that are grouped in a single archive (tar).

packet
 ├── ca.crt
 ├── client.ovpn
 ├── credentials.txt
 └── ta.key
  • ca.crt: The master Certificate Authority certificate.
  • client.ovpn: The client’s VPN configuration file.
dev tun0
ns-cert-type server
proto tcp
script-security 2
client
topology subnet
remote 212.227.98.217 1194
nobind
tls-exit
ping-restart 120
comp-lzo
verb 3
ca /etc/openvpn/ca.crt
tls-auth /etc/openvpn/ta.key 1
route-up "/sbin/route add -net 10.0.0.0 netmask 255.255.255.0 dev tun0"
auth-user-pass /etc/openvpn/credentials.txt
  • credentials.txt: The file with username and password.
we500_53cb3e08006d_150890cH7k7c9bABbaldfVFBasUXDtQ5eG
9650f42c851c6de552a646e31lPc6Y1oOfegI5CgXPqSMrnNHO2uY
  • ta.key: The shared-secret key for the tls-auth.
POST
Not allowed.
PUT
Not allowed.
DELETE
Not allowed.

More information on how the WE500 uses a VPN can be found in the WE500 VPN section.