API

1. Introduzione
2. API overview
3. Risorse della API

1. Introduzione

Questa sezione è utile per gli utenti che vogliono stabilire una comunicazione tra il portale e altre piattaforme come ad esempio sistemi di fatturazione o di analisi dei dati per fare delle previsioni.

È altrettanto utile per sviluppare mobile app che interagiscono con il portale senza il bisogno di connettersi direttamente ad ogni singolo dispositivo.

2. API overview

Questo documento descrive la API esposta dal portale Nethix. È basata sullo scambio di documenti XML attraverso HTTP seguento il più possibile i principi REST.

La API espone i seguenti tipi di risorse:

API key
Customer
Domain
Device
Variable
Portal log

Il fine della API è quello di rendere possibile la creazione, modifica e la cancellazione di tali risorse. In generale queste operazioni sono mappate sui metodi HTTP.

La API è basata su risorse. Ogni risorsa è raggiungibile tramite un URL e, a seconda del metodo HTTP utilizzato, il server eseguirà la richiesta desiderata. I metodi HTTP supportati dalla API sono:

GET - ottiene un documento XML che descrive la risorsa richiesta
POST - crea una nuova risorsa
PUT - modifica una risorsa
DELETE - cancella una risorsa
OPTIONS - ottiene una lista dei metodi HTTP supportati
HEAD - come il metodo GET ma non restituisce una risposta

Gli ultimi due metodi sono implementati per ogni risorsa e non sono specificati sei capitoli successivi.

Il server risponde ad ogni richiesta ricevuta con una risposta HTTP contenente uno dei seguenti codici di stato HTTP:

Codice di stato	Descrizione
200 OK	La richiesta di creare una nuova richiesta è stata eseguita.
201 Created	La richiesta di creare una nuova richiesta è stata eseguita.
400 Bad request	La richiesta non risponde a queste specifiche.
401 Unauthorized	Il client non ha i privilegi necessari.
404 Not found	La risorsa non esiste.
405 Not Allowed	Il metodo HTTP usato non è supportato da questa risorsa.
408 Request Timeout	La richiesta è scaduta.
409 Conflict	La richiesta è in conflitto con la risorsa corrente. Per esempio se una risorsa viene creata due volte, la seconda restituirà l’errore di conflitto.
500 Internal Server Error	Si è verificato un errore nel server.

Tutte le richieste richiedono che il client abbia determinati privilegi.

La API supporta due metodi di autenticazione:

HTTP Basic Authentication
Fornendo una API key nella richiesta

In particolare la API key può essere inserita nella query string usando api_key come nome, o questo frammento di codice XML:

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

Notare che il metodo HTTP GET non permette di allegare alcun documento nella richiesta, quindi in questo caso la API key andra inserita nella query string.

3. Risorse della API

3.1. API key

Una API key è un token che viene utilizzato per identificare il client. Questa risorsa deve essere sempre chiamata prima di richiamare ogni altra risorsa, in caso contrario il client non sarà autorizzato all’accesso della risorsa desiderata.

Durante una sessione, la prima richiesta a questa risorsa serve per inviare il login e la password del client. La risposta , se le credenziali sono corrette, sarà la API key usata per le successive richieste.

Per ragioni di sicurezza ogni sessione avrà una API key differente.

URL

/api/v1/api_key

GET

Parameters

Se non è stata fornita una API key valida o non viene utilizzato il metodo di autenticazione HTTP Basic allore devono essere forniti i seguenti parametri:

login
password

Response

<ntx>
    <authentication>
        <api_key>6sBtnYrMhgEehQuY1LA6TRYVArj3YfRI</api_key>
    </authentication>
</ntx>

POST: Non permesso.
PUT: Non permesso.
DELETE: Non permesso.

3.2. Cliente

Rappresenta il cliente di chi effettua la richiesta.

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: Non permessa.
PUT: Non permessa.
DELETE: Non permessa.

3.3. Dominio

Rappresenta un insieme di dispositivo.

URL

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

Se nessun ID viene specificato nello URL allora la risposta sarà di tutti i domini.

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: Non permesso.
PUT: Non permesso.
DELETE: Non permesso.

XML Tags

vpn_enable - 1 se la VPN del dominio è abilitata, 0 in ogni altro caso

3.4. Dispositivo

Un dispositivo fisico Nethix (es. WE500).

URL

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

Se non è fornito alcun ID di un dispositivo allora lo URL sarà indirizzato a tutti i dispositivi.

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>
      <vpn_status>1</vpn_status>
      <device_nethix>
        <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_nethix>
    </device>
  </devices>
</ntx>

POST: Non permesso.
PUT: Non permesso.
DELETE: Non permesso.

XML Tags

type - il tipo di dispositivo, i valori possibili sono:
- 1 - WE500
- 2 - PC
last_ip - rappresentazione in numero intero dell’ultimo indirizzo IP ricevuto dal dispositivo
vpn_status - stato della VPN:
- 1 - ONLINE
- 2 - OFFLINE

3.5. Variabile

Una variabile del dispositivo che è stata inviata al portale almeno una volta.

URL

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

Se nessun id è specificato lo URL sarà indirizzato a tutte le variabili.

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: Non permesso.
PUT: Non permesso.
DELETE: Non permesso.

XML Tags

access_mode -
- 0 - Sola lettura
- 1 - Sola scrittura
- 2 - Lettura-Scrittura
protocol -
- 0 - Ingresso analogico
- 1 - Ingresso digitale
- 2 - Uscita digitale
- 3 - Modbus
- 4 - variabile virtuale
active_label- Valore da mostrare quando il valore è 1
inactive_label - Valore da mostrare quando il valore è 0
size - Il numero di bit che compongono la variabile (valido solo per le variabili modbus)

3.6. Log inviato al portale

Un log inviato al portale è un semplice insieme di variabili e dei loro valori in uno specifico istante temporale.

URL

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

Se nessun id è specificato allora lo URL sara indirizzato a tutti logs del dispositivo .

GET

Parameters

Questo metodo accetta i seguenti parametri in ordine per perfezionare il risultato:

from_ts - Istante di partenza. Deve essere un UNIX timestamp
to_ts - Istante finale. Deve essere un UNIX timestamp
limit - Il massimo numero di log che devono essere contenuti nella risposta (defaul: 10)
offset - Se specificato saranno mostrati i primi X log (dove X è il limit) del range di tempo specificato a partire dall’n-esimo log (dove n è offset + 1)

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>

Esempio

Richiesta 1:

/api/v1/device/1/portal_log?api_key=xxxxyyyyyyyzzzzz&limit=1

<ntx>
  <portal_log>
    <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>
    </variables>
  </portal_log>
</ntx>

Utilizzando limit 1 viene restituito il primo log.

Richiesta 2:

/api/v1/device/1/portal_log?api_key=xxxxyyyyyyyzzzzz&limit=1&offset=1

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

Utilizzando offset 1 e limit 1 viene restituito il secondo log.

3.7. Variabile in tempo reale

Restituisce il valore in tempo reale delle variabili del dispositivo inviate al portale.

URL

/api/v1/device/device_id/rt_variable(/(variable_id_or_name;)*)?

Se non è specificato nessun ID o nome allora verrà restituito il valore di tutte le variabili in tempo reale del dispositivo.

Se vengono utilizzati i nomi delle variabili allora è necessario utilizzare il parametro: _byname

GET

Parameters

Questo metodo accetta i seguenti parametri in ordine per perfezionare il risultato:

_byname - indica se gli identificativi delle variabili sono dei nomi o degli ID
- true - gli identificativi sono dei nomi
- false - gli identificativi sono degli ID

Response

<ntx>
  <variables>
    <variable>
      <name>Pump</name>
      <id>1</id>
      <status>
        <value>1</value>
        <value_prev>0</value_prev>
        <alarm_active>0</alarm_active>
        <alarm_visible>0</alarm_visible>
      </status>
    </variable>
    <variable>
      <name>Temperature</name>
      <id>2</id>
      <status>
        <value>23.54</value>
        <value_prev>22.89</value_prev>
        <alarm_active>0</alarm_active>
        <alarm_visible>1</alarm_visible>
      </status>
    </variable>
  </variables>
</ntx>

POST

Non permesso.

PUT

Imposta il valore corrente di una variabile. Può essere utilizzato solamente su variabili di tipo write only o read/write.

Nello URL è permesso specificare un solo ID o nome di una variabile.

Richiesta:

<ntx>
    <value>on</value>
</ntx>

DELETE

Non permesso.

3.8. VPN

Richiesta dei dati/stato della VPN utili per connettersi ad essa.

Questa risorsa è usata da WE500 per ottenere i dati necessari per stabilire la connessione VPN con il portale. Al cliente è utile conoscere questa risorsa per stabilire una VPN tra WE500 ed un portale che non sia quello di Nethix.

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: Non permesso.
PUT: Modifica lo stato della VPN.
Request: Al momento solo i dispositivi possono usare questo metodo per cambiare lo stato della VPN da aggiornare la configurazione del client (3) a abilitato (2)

<ntx>
    <vpn>
        <status>2</status>
    </vpn>
</ntx>

DELETE: Non permesso.

XML Tags

recconnection_time - quando la VPN non è abilitata, il client aspetterà questo tempo (ins econdi) prima di effettuare una nuova richiesta per los tato della VPN.
status - stato della VPN, può assumere i seguenti valori:
- 1 : Disabilitato
- 2 : Abilitato
- 3 : Aggiornare la configurazione del client
Quanfo lo stato è disabilitato, la risposta non avrà il tag package_info.
auth_type - meccanismo di autenticazione della VPN, può assumere i seguenti valori:
- 0 : Login e password
md5_ca_cert - MD5 del file ca.crt
md5_client_conf - MD5 del file client.ovpn
md5_ta_key - MD5 del file ta.key
md5_credentials - MD5 del file credentials.txt

I file vengono trasmetti in un singolo file compresso e verificati con questi checksums.

Maggiori informazioni su come il WE500 utilizza una VPN possono essere trovate nella sezione 10.2.2. VPN.

3.9. Pacchetto VPN

Scarica i file necessari per stabilire una connessione VPN.

Questa risorsa è usata solo dofo che il WE500 ha ricevuto uno stato di aggiornare la configurazione del client (3) in risposta ad una richiesta sulla risorsa 3.8. VPN. Al cliente è utile conoscere questa risorsa per stabilire una VPN tra WE500 ed un portale che non sia quello di Nethix.

URL: /api/v1/vpn/packet

GET

Response

Restituisce i file VPN raggruppati in un singolo archivio (tar).

packet
 ├── ca.crt
 ├── client.ovpn
 ├── credentials.txt
 └── ta.key

ca.crt: Il master Certificate Authority certificato.
client.ovpn: Il file di configurazione del client VPN.

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: Il file con username e password

we500_53cb3e08006d_150890cH7k7c9bABbaldfVFBasUXDtQ5eG
9650f42c851c6de552a646e31lPc6Y1oOfegI5CgXPqSMrnNHO2uY

ta.key: La shared-secret key per la tls-auth.

POST: Non permesso.
PUT: Non permesso.
DELETE: Non permesso.

Più informazioni su come il WE500 utilizza la VPN possono essere trovate nella sezione 10.2.2. VPN.