Beschreibung

Die REST-Schnittstelle ermöglicht es, verschiedene Konfigurationen der STARFACE aus einer eigenen Anwendung zu steuern. Sie basiert auf einem einfachen zustandslosem Protokoll, welches Zugriff auf verschiedene Ressourcen der STARFACE ermöglicht. Die Abfragen werden über unterschiedliche HTTP-Methoden durchgeführt.

HTTP-Methoden

BefehlBeschreibung
GETFordert die angegebene Ressource vom Server an. Die Konfiguration am Server wird nicht verändert, weshalb GET als sicher bezeichnet wird
POSTFügt eine neue Ressource hinzu und wird für die Authentifizierung verwendet
PUTDie angegebene Ressource wird geändert
DELETELöscht die angegebene Ressource

Ressourcen

TypBeschreibung
LoginWird benötigt zur Authentifizierung der Schnittstelle
Call ServicesAbfrage der CallServices
ConferencesAbfrage und Änderung von "Moderierten Konferenzen"
ContactsAbfrage von Adressbüchern, Schema und Adressen; Hinzufügen, ändern und löschen von Adressen
Function keysAbfrage, hinzufügen, ändern und löschen von Funktionstasten für Benutzer
GroupsAbfrage, hinzufügen, ändern und löschen von Gruppen
iFMCAbfrage, hinzufügen, ändern und löschen von iFMC-Konfigurationen für Benutzer
LicensesAbfrage und hinzufügen von Benutzerlizenzen 
PermissionsAbfragen und ändern von Benutzerrechten
Phone NumbersAbfrage, hinzufügen, ändern und löschen von Rufnummernzuordnungen zu Benutzern
PushAbfrage und ändern der Chatbenachrichtigung via Push
RedirectsAbfrage und Änderung von Umleitungen
Server/ActionsServer & Dienste herunterfahren oder neu starten
Server/LanguageAbfragen und ändern der Serversystemsprache
Server/LicensesAbfragen und ändern von Lizenzen und automatischer Lizenzzuordnung
Server/MailAbfragen und ändern von Mailserverkonfiguration
Server/StateAbfragen des aktuellen Status der Serverdienste
Server/TimeAbfragen und ändern der Zeit-/Datumseinstellungen
Server/UpdatesAbfragen und ändern der Updateinstellungen
Server/VersionAbfragen der Serverversion
Server/WebserverAbfragen und ändern der http- und https-Webserverkonfiguration
STARFACE NEONAbfrage der STARFACE NEON Authentifizierung eines Nutzers
UsersAbfrage von Nutzern und Nutzerstammdaten; Hinzufügen, ändern und löschen von Nutzern; Abfrage, hinzufügen, ändern und löschen von Telefonen zu Benutzern
Voicemail BoxesAbfragen, hinzufügen und löschen von Voicemailboxen

Zugriff

Der Zugriff auf die Schnittstelle ist über die Basis-URL der STARFACE, inklusive dem Zusatz /rest möglich.

http://[IP/URL der STARFACE]:80/rest
https://[IP/URL der STARFACE]:443/rest

Authentifizierung

Zur Absicherung der REST-Schnittstelle, muss bei jeder Abfrage ein Authentifizierungstoken mitgesendet werden. Dieser Token muss vor der Verwendung weiterer Abfragen generiert werden und ist dann für 4 Stunden gültig. Diese Abfrage funktioniert in dieser Form, ab der Version 6.4.2.12 der STARFACE.

Schritt 1

Die Adresse der STARFACE für dieses Beispiel ist: https://example.starface-cloud.com

HTTP-GET zu https://example.starface-cloud.com/rest/login

Content-Type=application/json
X-Version=2
 
Rückgabe:
{
"loginType":"Internal",
"nonce":"pds24hmip1ctbogn1l8ujvs5u4",
"secret":null
}

Schritt 2

Die Generierung des verschlüsselten Passworts (secret) wird folgendermaßen aufgebaut:

LoginID:SHA512(LoginID+nonce+SHA512(password))

Hinweis: Bei Nutzung eines Active Directory bildet sich das Passwort (secret) nicht aus den SHA Hashes sondern aus dem folgenden Aufbau:

Base64Encode(LoginID+nonce+password)

Das folgene Beispiel geht davon aus das die folgenden Zugangsdaten genutzt werden:

BeschreibungWert
Benutzer0001
Kennwortpassword

Das SHA512 von „password“ ist b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86

Unser Secret berechnet sich also so:

0001:SHA512(0001pds24hmip1ctbogn1l8ujvs5u4b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86)”

Hinweis: Die farblichen Markierungen dienen außschließlich der optischen Trennung der verschiedene Teilstücke.

Was folgenden String ergibt:

0001:8763072240d007e18b92ce58ce76bb244377e1f41bde6811ce7c17adab4977f0d00502a6a9a1b1d70a51824626b86df82699fe993b458a4818817375078983b3

Schritt 3

Der in Schritt 2 ermittelte String kann mit einem POST auf http://host/rest/login mit folgendem Body verwendet werden:

HTTP-POST zu https://example.starface-cloud.com/rest/login

Header:
{
Content-Type : application/json
X-Version : 2
}
 
Body:
{
"loginType": "Internal",
"nonce": "pds24hmip1ctbogn1l8ujvs5u4",
"secret": 
"0001:8763072240d007e18b92ce58ce76bb244377e1f41bde6811ce7c17adab4977f0d00502a6a9a1b1d70a51824626b86df82699fe993b458a4818817375078983b3"
}


Rückgabe:
{
"authToken": "abcdef12345"
}

Bei erfolgreicher Authentifizierung findet sich im Response Body der Authentifizierungstoken

authToken=abcdef12345

Schritt 4

Der zurückgelieferte Authentifizierungstoken ist nun für 4 Stunden gültig und muss jeder weiteren Abfrage als Header vom Typ authToken hinzugefügt werden (z.B. authToken:abcdef12345).

Beispiel für die Authentifizierung

Für dieses Beispiel der Authentifizierung wurde Python 3.6.3 verwendet. Dabei wurden nur mitgelieferte Libraries genutzt.

Python-Login.py

In der folgenden Beispieldatei wird zusätzlich zum Login auch noch gezeigt, wie ein json-Element anlegt und als Payload an den Server mitgesendet wird.

Python-LoginAndCreateUser.py

Swagger-Dokumentation

Die umfangreiche Dokumentation ist als Swagger-Datei verfügbar und kann mit dem Swagger-Editor gelesen werden (siehe auch http://editor.swagger.io/). Im Editor wird die Datei über den Menüpunkt "File / Import File ..." geladen. Alle Swagger-Dateien ab der Version 6.7.X.X. können direkt auf der Weboberfläche der jeweiligen STARFACE heruntergeladen werden (siehe auch Serverkonfiguration der STARFACE konfigurieren).

VersionDownload
6.6.0
6.5.1
6.5.0