REST - Schnittstelle

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

Befehl	Beschreibung
GET	Fordert die angegebene Ressource vom Server an. Die Konfiguration am Server wird nicht verändert, weshalb GET als sicher bezeichnet wird
POST	Fügt eine neue Ressource hinzu und wird für die Authentifizierung verwendet
PUT	Die angegebene Ressource wird geändert
DELETE	Löscht die angegebene Ressource

Ressourcen

Typ	Beschreibung
Login	Wird benötigt zur Authentifizierung der Schnittstelle
Adressbuch	Abfrage von Adressbüchern, Schema und Adressen; Hinzufügen, ändern und löschen von Adressen
Benutzer	Abfrage von Nutzern und Nutzerstammdaten; Hinzufügen, ändern und löschen von Nutzern
Umleitungen	Abfrage und Änderung von Umleitungen
iFMC	Abfrage, hinzufügen, ändern und löschen von iFMC-Konfigurationen
Funktionstasten	Abfrage, hinzufügen, ändern und löschen von Funktionstasten

Zugriff

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

Beispiel

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

Authentifizierung

Zur Absicherung der REST-Schnittstelle, muss jeder Abfrage ein Authentifizierungstoken mitgesendet werden. Dieser Token muss vor der Verwendung weiterer Abfragen vorher generiert werden und ist dann für 4 Stunden gültig. Die nötige Authentifizierung läuft in 3 Schritten ab.

Abfrage eines Login-Objekts, inklusive eines zufälligen Schlüssels (nonce)
Verschlüsselung der Zugangsdaten mit dem zufälligen Schlüssel
Abfrage des Authentifizierung-Tokens, durch senden der verschlüsselten Zugangsdaten

Beispiel

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

Schritt 1

HTTP-GET zu https://example.starface-cloud.com/rest/login
 
Rückgabe:
{
"loginType":"Internal",
"nonce":"uanedh2tu7s7vn2t4bk6qrlidi",
"secret":null
}

Schritt 2

Zur Generierung des verschlüsselten Passworts (secret) werden nun die Zugangsdaten mit dem nonce zusammen gefügt. Die Daten werden nach folgendem Muster zusammengebaut: loginId + nonce + password

Bevor die Daten verwendet werden können, muss aus dem Ergebnis noch ein Hash-Wert ermittelt werden. Je nach Konfiguration der STARFACE, werden zwei unterschiedliche Verfahren verwendet. Bei der internen Authentifizierung wird ein SHA1-Hash und beim Einsatz eines ActiveDirectorys ein BASE64-Hash benötigt. Dieser Hash wird in die Variable secret eingetragen und per HTTP-Post an das System gesendet.

HTTP-POST zu https://example.starface-cloud.com/rest/login
 
Body:
{
"loginType":"Internal",
"nonce":"uanedh2tu7s7vn2t4bk6qrlidi",
"secret":"d3510d1bd33fe82bfcb027632c3dd42abf50da88"
}
 
Rückgabe:
{
"token": "4hknthnscpgv4cv0kltgj6lm6n"
}

Schritt 3

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

Swagger-Dokumentation

Die Umfangreiche Dokumentation ist als Swagger-Datei verfügbar. Zum lesen der Doku, kann unter Anderem der Swagger-Editor verwendet werden. Diesen finden Sie unter http://editor.swagger.io/.

im Editor laden Sie Datei über den Menüpunkt File / Import File ...

Seitenhierarchie