Topal REST Service
Ein Representational State Transfer (REST) Service dient der Maschine-zu-Maschine-Kommunikation. Damit eine 3. Applikation mit Topal Finanzbuchhaltung
kommunizieren kann, steht im Topal Server ein REST Service zur Verfügung. Damit 3. Applikationen diesen REST Service verwenden können, ist dieser zu konfigurieren
kommunizieren kann, steht im Topal Server ein REST Service zur Verfügung. Damit 3. Applikationen diesen REST Service verwenden können, ist dieser zu konfigurieren
und entsprechend vor der Verwendung zu starten. Die Topal WebSolution die Bestandteil der Topal Finanzbuchhaltung ist, kann im Kontext der Architektur auch als 3. Applikation
betrachtet werden und verwendet diesen REST Service in gleicherweise.
Die Konfiguration des REST Services finden Sie in den folgenden Kapiteln. Zur Beschreibung und Verwendung des REST API's ist das Swagger Framework verwendet worden.
Die Beschreibung der REST API Funktionen sind via [Topal Server Agent | Netzwerk Einstellungen] zu öffnen. Folgen Sie den unten beschriebenen Schritten um den interaktiven
Zugriff via REST API zu erhalten.
Zugriff via REST API zu erhalten.
1) Öffnen Sie [Topal Server Agent | Netzwerk Einstellungen]
2) Konfiguration der REST Umgebung und Ports
3) Öffnen der interaktiven Swagger REST API Dokumentation
4) Token Konfiguration
Konfiguration der REST Umgebung
Topal Server Agent "REST API"
Die Einstellungen in diesem Bereich beziehen sich auf die Konfiguration des REST API Hosts respektive der Port und Zugriffs Tokens.
Der REST API Service ist Bestandteil der Topal Finanzbuchhaltung und wird durch aktivieren der Checkbox [Host REST API] aktiviert. Die Angabe des [Port's] wir auch
für den Zugriff auf die WebSolution verwendet.
1) Aktivieren des Host REST API
2) Port (z.B. 9001)
3) Aktivieren von Https
4) Hinzufügen von Zertifikaten (Topal Server Zertifikat), um Secure via HTTPS zu kommunizieren.
(Die Erstellung von Self Signed Zertifikaten finden Sie in Kapitel SSL Kommunikation)
(Die Erstellung von Self Signed Zertifikaten finden Sie in Kapitel SSL Kommunikation)
Bemerkung:
Die Verwendung des REST API's kann auch für 3. Applikationen verwendet werden. Die Beschreibung zum REST API finden in den folgenden Kapiteln.
Beispiele zur Verwendung des REST API's sind auch auf der Topal Developer Page (https://developer.topal.ch) zu finden.
Verwenden Sie einen Port den Sie bis dato noch für keine andere Applikation verwendet haben.
Topal verwendet standardmässig den Port Range (5001 - und folgende) entsprechend der Konfiguration ihrer Topal Instanzen. Aus Sicht Topal ist es sinnvoll den Port ab 9000 zu
Topal verwendet standardmässig den Port Range (5001 - und folgende) entsprechend der Konfiguration ihrer Topal Instanzen. Aus Sicht Topal ist es sinnvoll den Port ab 9000 zu
wählen. Dies ist aber abhängig von Ihrer Netzwerk Infrastruktur.
Öffnen der Swagger REST API Dokumentation
Die REST API Dokumentation können Sie via Link [Visit API Page] öffnen (siehe Abbildung 1 - Punkt 1). Ein Browser wird wird gemäss Abbildung 2 wird geöffnet.
Bemerkung:
Sollten Sie die API Page nicht öffnen können, kann dies daran liegen, dass der Topal Server service Benutzer den Sie hinterlegt haben keinen der verwendeten Ports öffnen kann.
Dies ist ein Berechtigungsproblem und muss durch Ihren IT Admin gewährleistet werden.
Dies ist ein Berechtigungsproblem und muss durch Ihren IT Admin gewährleistet werden.
Abbildung 1: Zugriff REST API Dokumentation
Abbildung 2: Swagger REST API Dokumentation
Datenabfrage via Swagger
Um Daten interaktiv via Swagger vom Topal Server zu lesen, ist es notwendig den Zugriffs Token zu verwenden.
Was ist ein Zugriffs - Token:
Ein Zugriffstoken ist ein Objekt, das den Sicherheitskontext eines Prozesses beschreibt. Die Informationen in einem Token enthalten die Identität und die
Berechtigungen des Benutzerkontos, die dem Prozess oder dem Thread zugeordnet sind. Wenn sich ein Benutzer anmeldet, überprüft das System das
Passwort des Benutzers, indem es es mit Informationen vergleicht, die im Benutzer Management von Topal gespeichert sind. Wenn das Passwort authentifiziert
wird, erzeugt das System ein Zugriffstoken. Jeder Prozess, der im Auftrag dieses Benutzers ausgeführt wird, hat eine Kopie dieses Zugriffstokens.
Ein Zugriffstoken ist ein Objekt, das den Sicherheitskontext eines Prozesses beschreibt. Die Informationen in einem Token enthalten die Identität und die
Berechtigungen des Benutzerkontos, die dem Prozess oder dem Thread zugeordnet sind. Wenn sich ein Benutzer anmeldet, überprüft das System das
Passwort des Benutzers, indem es es mit Informationen vergleicht, die im Benutzer Management von Topal gespeichert sind. Wenn das Passwort authentifiziert
wird, erzeugt das System ein Zugriffstoken. Jeder Prozess, der im Auftrag dieses Benutzers ausgeführt wird, hat eine Kopie dieses Zugriffstokens.
Beispiel eines Tokens:
{"access_token":"Bearer AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAtzMYbZzjAEy8prvutuhvOwAAAAACAAAAAAAQZgAAAAEAACAAAACX6QI66F0Zo6pQjbXqNB62aj797KalmlBf3P6qVzfncgAAAAAOgAAAAAIAACAAAABGYCFA1XkjCDAtAsL4vPyd7U7L2pvH05E33bZlfNBQwSABAABk8u4Ds5D1RPa-WymjOaa8lzNPxhk1tOgBRdnqIqZ6bgrYF8GOjg0ZOVIHQ5P5T
{"access_token":"Bearer AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAtzMYbZzjAEy8prvutuhvOwAAAAACAAAAAAAQZgAAAAEAACAAAACX6QI66F0Zo6pQjbXqNB62aj797KalmlBf3P6qVzfncgAAAAAOgAAAAAIAACAAAABGYCFA1XkjCDAtAsL4vPyd7U7L2pvH05E33bZlfNBQwSABAABk8u4Ds5D1RPa-WymjOaa8lzNPxhk1tOgBRdnqIqZ6bgrYF8GOjg0ZOVIHQ5P5T
jYvxekXJNkdGhcegMQ71_EOrjI10GVkLJLa9EGxROtG3oFdcKr0oj26ojCbo6lsQAFs4JPsnWb-VSAGoPFKM_F3fyVPXLiDULcWIH3vajazY8-qQgTv0KTzmnyqJOUhcsN2kb1yIdpzRqXJ
3sJpQfwYygd4bNVuqAEZKXZTFj_Qv-A04v9uF2t5xqTtYDcayDyH3CV_W-eTOd1AYV-9NwrNNVp24Rj-4fULaLBA_wTJsWUkgVdRIpKz6Pgm8IscyOxjtHlV__O_9xVbDT7r4VxfwfBS
GIvv9bZHKjsDHAPKT5iRrnTH_iaJ5ygylZMZaCxAAAAAnHv0I_Cvj2_vdeVJzRiDuxHH8Lr7kAXAy60jXRyD8QaGry2J37YxgLHnShEbdBeFjJGTN1nF1R7ugNdB3jgzKw","token_type":"bearer","expires_in":86399,"userName":"APIUser",".issued":"Tue, 18 Apr 2017 10:22:57 GMT",".expires":"Wed, 19 Apr 2017 10:22:57 GMT"}
Kopieren des Tokens
Wählen Sie den Button [Zugriffs Token lesen]. Fügen Sie den User - Namen ein und klicken Sie den Button [Token lesen]. Der Token wir im Textfeld angezeigt.
Kopieren Sie den Token und fügen Sie diesen im Textfeld (Abbildung2 - Punkt 3). Nachdem Sie diesen Schritt vollzogen haben, können Sie auf die Topal Ressourcen zugreifen.
Auslesen der Topal Daten
In Abbildung 2 ist ein Beispiel von Zugriffsmethoden für Parties gezeigt. Diese Zugriffsmethoden können Sie in Ihrer 3. Applikation verwenden um auf Daten in Topal zuzugreifen.
Wählen Sie nun zum Beispiel Clients an und füllen Sie die erforderlichen Felder aus. Drücken Sie dann [Try it out]. Die gewünschten Informationen werden gelesen und
angezeigt (siehe Abbildung 3).
angezeigt (siehe Abbildung 3).
Abbildung 3: Lesen von Daten via REST API