Panoramica

Questa sezione della documentazione ha lo scopo di avviare lo sviluppatore alla realizzazione di un'applicazione reale che sfrutti le REST API di NethCTI. Gli argomenti trattati sono quelli dell'autenticazione, dell'utilizzo delle REST API e della comunicazione bidirezionale via WebSocket.

In tal modo lo sviluppatore sarà in grado di realizzare applicazioni in grado di mostrare informazioni in tempo reale e di poter effettuare operazioni di ogni genere.

Autenticazione

Lo scopo della fase d’autenticazione è creare un token che sarà usato per le operazioni future, quali l’invocazione delle REST API o per creare una connessione permanente (WebSocket o TCP).

Eseguire il login

  1. Il client invia una richiesta HTTPS (POST) alla seguente rest api:

https://<SERVER>/webrest/authentication/login

specificando lo username e password in formato JSON:

{ "username": "my_user", "password": "my_password" }

  1. Il client riceve una risposta standard HTTPS 401. Se l'autenticazione ha avuto successo la risposta contiene un nonce (una stringa) nello header HTTPS, altrimenti l'autenticazione è fallita. Un esempio di header è (il nonce è 06d15944d8ece69bdc97742b37c507970e2f6651):

www-authenticate: Digest 06d15944d8ece69bdc97742b37c507970e2f6651

  1. Il client calcola il token:

tohash = username + ':' + password + ':' + nonce
token  = HMAC-SHA1(tohash, password)

  1. Il client memorizza il token per usi futuri.

Se il token d'autenticazione non viene mai usato, scade dopo un certo periodo di tempo (il default è mezz'ora). Una nuova fase d'autenticazione è necessaria.

Eseguire il logout

  1. Il client invia una richiesta HTTPS (POST) alla seguente rest api:

https://<SERVER>/webrest/authentication/logout

  1. Il token viene rimosso dal server.

REST API

Le REST API sono dei Web Services che consentono l'interazione con il server NethCTI. È uno strumento molto utile per l'integrazione e lo sviluppo.

Nota

Questo documento assume che il lettore possegga già una certa familiarità con le più comuni tecniche di programmazione e Web Services.

Come usare una API

Di seguito vengono elencate le caratteristiche comuni a tutte le REST API:

  • una API viene invocata tramite l'invio di una richiesta HTTPS al server NethCTI che risponde fornendo i dati richiesti o tramite un codice di stato o entrambi.

  • I codici di stato delle risposte HTTPS sono quelli standard.

  • Il formato utilizzato per lo scambio dati è JSON.

  • Tutte le risorse sono raggiungibili tramite l'urli base:

https://<SERVER>/webrest/

  • Per richiedere una API è necessario aggiungere un patì al baseurl che specifica la risorsa da richiedere. Per esempio:

https://<SERVER>/webrest/phonebook/search

  • Ogni richiesta deve contenere i parametri d'autenticazione per il controllo d'accesso, specificando lo header HTTPS Authorization:

Authorization: username:token

  • Ogni richiesta viene autenticata e autorizzata del server NethCTI.

Autenticazione

  1. L'autenticazione di una richiesta REST viene eseguita dal server controllando la validità del token passato. Quindi, come fase preliminare, Il client deve eseguire il login e deve creare un token d'autenticazione come descritto qui.

  2. Ogni richiesta deve contenere lo header HTTPS Authorization:

Authorization: username:token

La validità del token d'autenticazione viene aggiornato ad ogni richiesta, altrimenti scade dopo un certo intervallo temporale (di default pari a un'ora). Dopo la scadenza è necessaria una nuova fase d'autenticazione.

Autorizzazione

Ogni richiesta REST API viene autorizzata dal server che controlla i permessi utente configurati dall'amministratore attraverso l'interfaccia di NethServer Enterprise.

Esempio d'uso

L'esempio seguente mostra come eseguire una richiesta rest tramite cURL. Lo strumento si può rivelare utile per eseguire dei test e per comprendere il meccanismo delle chiamate con maggior dettaglio.

  1. Supponiamo di volere effettuare la ricerca in rubrica del contatto nethesis per estrarre il numero telefonico. La prima operazione da eseguire è l'autenticazione (è necessaria solamente la prima volta per la costruzione del token).

curl --insecure -i -X POST -d 'username=my_user&password=my_password' https://192.168.5.226/webrest/authentication/login

L'autenticazione ha successo e il server risponde con:

HTTP/1.1 401 Unauthorized
Date: Thu, 12 Jun 2014 13:01:43 GMT
www-authenticate: Digest f4700adb35ad29ee16afe6c03c0196dfc74ec3b1
Content-Length: 0
Content-Type: text/plain

  1. Estraiamo il nonce dall'header www-authenticate:

f4700adb35ad29ee16afe6c03c0196dfc74ec3b1

  1. Costruiamo il token d'autenticazione:

$ echo -n 'my_user:my_password:f4700adb35ad29ee16afe6c03c0196dfc74ec3b1' | openssl dgst -sha1 -hmac 'my_password'
(stdin)= 1d8062d1c85a8fe6983745a1ee318d1cd9b8bde1

tohash = "my_user:my_password:f4700adb35ad29ee16afe6c03c0196dfc74ec3b1"
token  = HMAC-SHA1("my_user:my_password:f4700adb35ad29ee16afe6c03c0196dfc74ec3b1", "my_password") = "1d8062d1c85a8fe6983745a1ee318d1cd9b8bde1"

  1. Chiamiamo la rest api phonebook/search:

curl --insecure -i -H "Authorization: my_user:1d8062d1c85a8fe6983745a1ee318d1cd9b8bde1" https://192.168.5.226/webrest/phonebook/search/nethesis

  1. Il server invia la risposta in format JSON con i dati richiesti:

{
   "centralized": [
       {
           "id": 1916,
           "owner_id": "",
           "type": "Reseller",
           "homeemail": null,
           "workemail": "info@nethesis.it",
           "homephone": null,
           "workphone": "0721405516",
           "cellphone": "",
           "fax": "",
           "title": null,
           "company": "NETHESIS SRL ",
           "notes": "",
           "name": "",
           "homestreet": null,
           "homepob": null,
           "homecity": null,
           "homeprovince": null,
           "homepostalcode": null,
           "homecountry": null,
           "workstreet": "VIA DEGLI OLMI, 12",
           "workpob": null,
           "workcity": "PESARO",
           "workprovince": null,
           "workpostalcode": null,
           "workcountry": null,
           "url": "http://www.nethesis.it"
       }
   ],
   "nethcti": []
}

Elenco delle API

Qui la lista lista completa.

Utilizzo delle API del progetto Tancredi e Corbera

NethCTI supporta anche le redirezione di alcune chiamate rest api ai progetti Tancredi e Corbera in maniera autenticata. Ogni richiesta sarà autenticata tramite il metodo consueto (vedi la sezione apposita sopra) e sarà possibile invocare le api postponendo la keyword "tancredi" o "corbera" a quella "webrest", per esempio per interagire con l'api https://nethesis.github.io/tancredi/phonesMacGet:

https://<SERVER>/webrest/tancredi/api/v1/phones/<MAC_ADDRESS>

I metodi supportati sono GET e PATCH.

Qua la documentazione relativa alle API tancredi e corbera: http://api.nethesis.it/

WebSocket

La connessione WebSocket viene utilizzata dal server per comunicare in tempo reale con tutti i client connessi (ad esempio per notificare gli eventi del server Asterisk). Per stabilire una connessione WebSocket col server NethCTI è necessaria una prima fase d'autenticazione.

Eseguire il login

  1. Il client esegue il login e crea un nuovo token d'autenticazione come descritto qui

  2. Il client stabilisce una connessione websocket con il server sulla porta HTTPS 443:

socket = new io('https://server.domain.com', {
  "upgrade": false,
  "transports": ['websocket'],
  "reconnection": true,
  "reconnectionDelay": 2000
});

  1. Il client invia il messaggio login al server attraverso la connessione websocket specificando username e token in formato JSON:

socket.emit('login', { accessKeyId: username, token: token.toString() });

  1. Se il login ha avuto successo il client riceve il messaggio authe_ok, altrimenti il messaggio 401 e il client viene disconnesso.

Una volta completato il login con successo, il token ha validità infinita fino al riavvio del server.

Sottoscrizione eventi

Attraverso la connessione WebSocket vengono emessi i seguenti eventi:

Evento

Descrizione

extenUpdate

Aggiornamento di stato di un interno telefonico

extenConnected

Aggiornamento di stato di una chiamata connessa

updateNewVoiceMessages

Invia tutti i nuovi messaggi vocali in corrispondenza dell'arrivo di uno nuovo

newVoiceMessageCounter

Invia il numero di nuovi messaggi vocali in corrispondenza dell'arrivo di uno nuovo

queueMemberUpdate

Aggiornamento di stato di un agente di una coda

trunkUpdate

Aggiornamento di stato di un fascio

extenRinging

Notifica che un interno sta squillando e riporta l'identificativo del chiamante

queueUpdate

Aggiornamento di stato di una coda

parkingUpdate

Aggiornamento di stato di un parcheggio

wsClientLoggedIn

Un utente ha effettuato il login a NethCTI

allWsClientDisonnection

Un utente non ha più nessuna connessione WebSocket attiva

401

L'autenticazione è fallita

authe_ok

L'autenticazione è avvenuta con successo

Ogni evento fornisce i dati relativi in formato JSON.

È possibile sottoscrivere un ascoltatore per ciascuno degli eventi. Un esempio è il seguente:

socket.on('extenUpdate', function (data) {
    // all the code here
});