--- title: "Arbeiten mit der REST-Schnittstelle - icom Data Suite" slug: "working-with-the-ids-rest-interface-en" updated: 2024-12-11T09:20:05Z published: 2024-12-11T09:20:05Z canonical: "docs.insys-icom.com/working-with-the-ids-rest-interface-en" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.insys-icom.com/llms.txt > Use this file to discover all available pages before exploring further. # Arbeiten mit der REST-Schnittstelle - icom Data Suite REST steht für Representational State Transfer und stellt eine Schnittstelle für Konfiguration, Statusabfrage und Ausführung manueller Aktionen der icom Data Suite über das HTTP- und HTTPS-Protokoll zur Verfügung. Die HTTP(S)-REST-Schnittstelle erlaubt es, die **icom Data Suite** mithilfe von Skripten automatisiert zu konfigurieren oder Werte abzufragen. Im Folgenden finden Sie ein Beispiel für das Auslesen, Hinzufügen, Ändern und Löschen von Konfigurationen über die REST-Schnittstelle mit der App **Postman** und dem Web-basierten Tool **Swagger**. Dies soll Ihnen vermitteln, wie Sie die erforderliche Syntax für Befehl und übermittelten Konfigurationsinformationen (Payload) mithilfe verschiedener Tools ermitteln und an die icom Data Suite übertragen. Der Configuration Guide basiert auf einer **icom Data Suite** in Werkseinstellungen. Bei individuellen Konfigurationen kann die Beschreibung hinsichtlich Profilen, Adressen usw. abweichen. Die REST-Schnittstelle wird von der **icom Data Suite** ab der Version 1.5 unterstützt. Die genannten Tools sind nur Beispiele und dienen als Leitfaden für den Umgang mit der REST-Schnittstelle mithilfe externer Tools. > [!NOTE] > **Bitte beachten Sie!** > > Die REST-Schnittstelle des **Routers** selbst ist in diesem [Configuration Guide](/kb/docs/de/working-with-the-rest-interface-de) beschrieben. > [!NOTE] > **Bitte beachten Sie!** > > Die Dokumentation der REST API enthält sämtliche Befehle, die in der icom Data Suite auf den verschiedenen Konfigurationen und Ausstattungsvarianten des Routers verfügbar sind. Nicht alle enthaltenen Befehle werden von der icom Data Suite auf Ihrem Router unterstützt. icom Data Suite und REST API-Dokumentation müssen denselben Firmware-Stand haben. ## 1. Situation Folgende Konfigurationsschritte sollen über die REST-Schnittstelle erfolgen: - Abfragen der aktuell konfigurierten Benutzer der icom Data Suite - Hinzufügen eines neuen Benutzers - Ändern der Konfiguration dieses Benutzers - Löschen des neu hinzugefügten Benutzers ## 2. Lösung Die gesamte Dokumentation der REST API wird in Form einer JSON-Datei gemäß der OpenAPI-Spezifikation 3.0 aus der icom Data Suite heruntergeladen. Diese JSON-Datei wird in einem Tool wie dem Swagger Editor oder Postman geöffnet, um die Syntax für die Befehlsübermittlung zu ermitteln. Die angepassten Konfigurationsbefehle werden dann mit diesen Tools oder über einen cURL-Befehl an die icom Data Suite übermittelt. Stellen Sie sicher, dass Sie Zugriff auf das Web-Interface der icom Data Suite haben. ### 2.1. Aktivieren der REST-Schnittstelle und Herunterladen der REST API-Dokumentation 1. Web-Interface der icom Data Suite mit einem Browser aufrufen: [192.168.1.10](https://192.168.1.10) (Standard-Zugangsdaten: insys/icom) 2. Im Menü *Administration* → *REST-Interface* die Checkbox *REST-Interface via HTTPS aktivieren* markieren und auf *Einstellungen speichern* klicken. 3. Auf *REST API Dokumentation (OpenAPI als JSON)* klicken und die REST API-Dokumentation auf den Rechner herunterladen. ![cg de m3 rest interface 01](https://docs.insys-icom.de/assets/cg_de_m3_rest_interface_01.png) 4. Auf das blinkende Zahnrad in der Titelleiste ( ) klicken, um das Profil zu aktivieren. ### 2.2. Ermitteln der REST-Syntax und Übertragen der Konfigurationsbefehle an die icom Data Suite Ein besonders bequemer Weg hierfür sind REST API-Tools wie Postman und der Swagger Editor. Konfigurationsbefehle können auch mithilfe von cURL auch aus einer Kommandozeile heraus erfolgen. #### 2.2.1. Postman Die Postman-App ist ein nützliches Tool, um mit der icom Data Suite über die REST-Schnittstelle zu kommunizieren. Im Folgenden wird beschrieben, wie Sie in der Postman-App die REST API-Dokumentation der icom Data Suite importieren, die Zugangsdaten für die REST-Schnittstelle hinterlegen sowie die Umgebungsvariablen für die Kommunikation mit der icom Data Suite überprüfen. Weiter wird am Beispiel der Benutzerkonfiguration beschrieben, wie Sie mit Hilfe der Befehle **GET**, **POST**, **PUT** und **DELETE** Konfigurationen auslesen, hinzufügen, ändern und löschen. Außerdem erfahren Sie, wie Sie manuelle Aktionen ausführen. 1. Laden Sie die [Postman-App](https://www.postman.com/downloads/) herunter und installieren Sie diese. 2. Öffnen Sie die Postman-App 3. Klicken Sie auf die Schaltfläche *Import* im Bereich *My Workspace* oben links (oder im Menü *File* → *Import…​*) und öffnen Sie die oben heruntergeladene REST API-Dokumentation. 4. Klicken Sie auf *Show import settings*, aktivieren sie *Copy collections to workspace* und klicken Sie auf die Schaltfläche *Import*. ![cg en ids rest interface pm 01](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_01.png) 5. Klicken Sie auf die Schaltfläche *Close* um den Import abzuschließen. Die Dokumentation der REST API der icom Data Suite wird als Sammlung (Collection) angezeigt. 6. Fahren Sie über die neue Sammlung, klicken Sie auf *View more actions* und wählen Sie *Edit*. ![cg en ids rest interface pm 02](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_02.png) 7. Wechseln Sie im Feld der **icom Data Suite - REST API** auf die Registerkarte *Authorization*, wählen Sie den *Type* **Basic Auth** und geben Sie den *Username* und das zugehörige *Password* des Benutzers ein. Der Benutzer muss im Menü *Administration* → *Benutzer* der icom Data Suite mit Lese- und Schreibrechten angelegt sein. ![cg en ids rest interface pm 03](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_03.png) 8. Klicken Sie auf *Save collection*, um die Zugangsdaten in der Sammlung zu hinterlegen. 9. Wechseln Sie auf die Registerkarte *Variables* und überprüfen Sie die hinterlegten Variablen für Protokoll (HTTP oder HTTPS), IP-Adresse der icom Data Suite und Port für den HTTP-/HTTPS-Zugang. Mit der oben importierten REST API-Dokumentation werden hier die Standardwerte der icom Data Suite übergeben. Wurden diese geändert, müssen Sie hier angepasst werden. ![cg en ids rest interface pm 04](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_04.png) ##### 2.2.1.1. Abfragen der Benutzer-Konfiguration Der erforderliche HTTP-Befehl zum Auslesen von Ressourcen (Parameter bzw. Einträge) ist **GET**. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben. 1. Navigieren sie in der Sammlung *icom Data Suite - REST API* zu *configuration* → *administration* → *users* und klicken sie auf den Befehl **GET**. 2. Deaktivieren Sie im Abschnitt *Query Params* die Checkboxen für *profile*, *return_size* und *filter*. 3. Klicken Sie auf die Schaltfläche *Send*, um den GET-Befehl an die icom Data Suite zu senden. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **200 OK**. Sie enthält die Benutzer-Konfiguration der icom Data Suite. Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü *Administration* auf der Seite *Benutzer*. ![cg en ids rest interface pm 05](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_05.png)![cg de ids rest interface 02](https://docs.insys-icom.de/assets/cg_de_ids_rest_interface_02.png) ##### 2.2.1.2. Hinzufügen eines Benutzers Der erforderliche HTTP-Befehl zum Hinzufügen von Ressourcen (Parameter bzw. Einträge) ist **POST**. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben. 1. Navigieren sie in der Sammlung *icom Data Suite - REST API* zu *configuration* → *administration* → *users* und klicken sie auf den Befehl **POST**. 2. Wechseln Sie auf die Registerkarte *Body* und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein. ```plaintext {  "profile": {    "name": "Profile",    "activate": "0"  },  "config": {    "user": [      {        "active": "1",        "username": "CGTestUser",        "password": "icom",        "group": "read"      }    ]  } } ``` 1. Klicken Sie auf die Schaltfläche *Send*, um den POST-Befehl an die icom Data Suite zu senden. Mit diesem Befehl wird ein neuer **aktiver** Benutzer mit dem Benutzernamen **CGTestUser**, dem Passwort **icom** und der Benutzergruppe **Lesen** dem Profil **Profile** hinzugefügt, das anschließend nicht aktiviert wird. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **201 Created**. Die oben übertragene Konfiguration wird noch einmal angezeigt. ![cg en ids rest interface pm 06](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_06.png) Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü *Administration* auf der Seite *Benutzer* mit dem neu hinzugefügten Benutzer (um das Hinzufügen zu sehen, muss das laufende Profil in der icom Data Suite auch das Profil sein, zu dem der Benutzer hinzugefügt wurde, hier **Profile**). ![cg de ids rest interface 03](https://docs.insys-icom.de/assets/cg_de_ids_rest_interface_03.png) ##### 2.2.1.3. Ändern der Konfiguration eines Benutzers Der erforderliche HTTP-Befehl zum Hinzufügen von Ressourcen (Parameter bzw. Einträge) ist **PUT**. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben. 1. Navigieren sie in der Sammlung *icom Data Suite - REST API* zu *configuration* → *administration* → *users* und klicken sie auf den Befehl **PUT**. 2. Wechseln Sie auf die Registerkarte *Body* und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein. ```plaintext {  "profile": {    "name": "Profile",    "activate": "0"  },  "config": {    "user": [      {        "group": "readwrite",        "index": "user2"      }    ]  } } ``` 1. Klicken Sie auf die Schaltfläche *Send*, um den PUT-Befehl an die icom Data Suite zu senden. Mit diesem Befehl wird für den Benutzer mit dem Index **user2** im Profil **Profile** die Benutzergruppe auf **Lesen/Schreiben** gesetzt. Damit wird die Benutzergruppe des oben hinzugefügten Benutzers geändert. Der Index des Benutzers wird angezeigt, wenn man nach dem Hinzufügen noch einmal den GET-Befehl zur Abfrage der Benutzer-Konfiguration ausführt. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **200 OK**. ![cg en ids rest interface pm 07](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_07.png) Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü *Administration* auf der Seite *Benutzer* mit der geänderten Benutzergruppe (um das Hinzufügen zu sehen, muss das laufende Profil in der icom Data Suite auch das Profil sein, zu dem der Benutzer hinzugefügt wurde, hier **Profile**). ![cg de ids rest interface 04](https://docs.insys-icom.de/assets/cg_de_ids_rest_interface_04.png) ##### 2.2.1.4. Löschen eines Benutzers Der erforderliche HTTP-Befehl zum Hinzufügen von Ressourcen (Parameter bzw. Einträge) ist **DELETE**. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben. 1. Navigieren sie in der Sammlung *icom Data Suite - REST API* zu *configuration* → *administration* → *users* und klicken sie auf den Befehl **DEL**. 2. Tragen Sie auf der Registerkarte *Params* unter *Query Params* für den Abfrageparameter *profile* den Wert **Profile** ein. Damit werden alle Benutzer, die den Filterkriterien entsprechen, aus dem Profil **Profile** gelöscht. 3. Tragen Sie für den Abfrageparameter *filter* den Wert **{"p":"username","o":"like","v":"test"}** ein. Damit werden alle Benutzer aus dem angegebenen (oder dem zuletzt aktivierten, wenn kein Profil angegeben ist) Profil gelöscht, deren Benutzername ("p":"username") die Zeichenfolge **test** ("v":"test") enthält ("o":"like"). > [!NOTE] > Jeder Filter besteht aus drei Parametern: > > "p" : "zu filternder Paramater" "o" : "für den Filter zu verwendender Operator, entweder "eq" (equal, gleich) für eine genaue Übereinstimmung oder "like" (ähnlich) wenn die angegebene Zeichenfolge nur enthalten sein soll" "v" : "Wert nach dem der Parameter gemäß dem Operator gefiltert werden soll" 1. Klicken Sie auf die Schaltfläche *Send*, um den DELETE-Befehl an die icom Data Suite zu senden. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **200 OK**. ![cg en ids rest interface pm 08](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_08.png) Vergleichen Sie dazu die Konfiguration im Web-Interface der icom Data Suite im Menü *Administration* auf der Seite *Benutzer* mit dem nun wieder gelöschten Benutzer (um das Hinzufügen zu sehen, muss das laufende Profil in der icom Data Suite auch das Profil sein, zu dem der Benutzer hinzugefügt wurde, hier **Profile**). ![cg de ids rest interface 02](https://docs.insys-icom.de/assets/cg_de_ids_rest_interface_02.png) ##### 2.2.1.5. Manuelles Ausführen von Aktionen Die icom Data Suite ermöglicht das Ausführen einer Vielzahl von Aktionen, wie Neustart, Starten eines Timers, Meldungsversand oder Setzen eines Datenpunkts. Aktionen werden bei Eintreten eines Ereignisses ausgelöst, können aber auch manuell ausgelöst werden. Leider ist es nicht ohne weiteres möglich, die Syntax des JSON-Bodys für manuelle Aktionen in Postman zu ermitteln. Die erforderliche Syntax lässt sich jedoch über die CLI herausfinden. Siehe dazu die Seiten **Rest-Schnittstelle** → **Debugging und Auslösen manueller Aktionen** sowie **Ermitteln der Befehls-Syntax für CLI und REST-Schnittstelle** in der Online-Hilfe der icom Data Suite bzw. des Routers (für den an den Router übermittelten CLI-Befehl). ###### 2.2.1.5.1. Beispiel 1: Schalten der Info-LED In diesem Beispiel soll die **Info**-LED am Router manuell zum Blinken gebracht werden. Der erforderliche HTTP-Befehl zum manuellen Auslösen von Aktionen ist **POST**. 1. Navigieren sie in der Sammlung *icom Data Suite - REST API* zu *operation* und klicken sie auf den Befehl **POST**. 2. Wechseln Sie auf die Registerkarte *Body* und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein. ```plaintext {    "method" : "manual_action",    "params" : {        "type" : "m3_cli",        "options" : {            "command" : "help.debug.info_led.info_led=flash\nhelp.debug.info_led.submit"        }    } } ``` 1. Klicken Sie auf die Schaltfläche *Send*, um den POST-Befehl an die icom Data Suite zu senden. Mit diesem Befehl wird die **Info**-LED am Router zum Blinken gebracht. Analog dazu wird sie mit dem Wert **off** für den Parameter **info_led** deaktiviert oder mit **on** aktiviert. Der CLI-Befehl besteht aus den beiden Befehlen **help.debug.info_led.info_led=flash** zum Setzen der LED auf Blinken und **help.debug.info_led.submit** zum Übertragen des gesetzten Parameters, verbunden durch **\n** für einen Zeilenumbruch zwischen den beiden Befehlen. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **201 Created**. ![cg en ids rest interface pm 09](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_09.png) Beobachten Sie dazu auch die LED am Router. ###### 2.2.1.5.2. Beispiel 2: Setzen eines Analogwerts In diesem Beispiel soll der Merker **flag1** auf einen bestimmten Wert gesetzt werden. Dabei wird vorausgesetzt, dass in der icom Data Suite dieser Merker mit einem analogen Datentyp angelegt ist. Der erforderliche HTTP-Befehl zum manuellen Auslösen von Aktionen ist **POST**. 1. Navigieren sie in der Sammlung *icom Data Suite - REST API* zu *operation* und klicken sie auf den Befehl **POST**. 2. Wechseln Sie auf die Registerkarte *Body* und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein. ```plaintext {  "method": "manual_action",  "params": {    "type": "analog",    "options": {      "datapoint": "flag1",      "change": "set_to",      "set":"to_value",      "value":"123555"    }  } } ``` 1. Klicken Sie auf die Schaltfläche *Send*, um den POST-Befehl an die icom Data Suite zu senden. Mit diesem Befehl wird der analoge Datenpunkt (Merker) **flag1** auf den Wert **123555** gesetzt. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **201 Created**. ![cg en ids rest interface pm 10](https://docs.insys-icom.de/assets/cg_en_ids_rest_interface_pm_10.png) Öffnen Sie im Web-Interface der icom Data Suite die Seite *Status* → *Aktuelle Werte* und prüfen Sie, ob sich der Wert des Merkers **flag1** auf den entsprechenden Wert geändert hat. #### 2.2.2. Swagger Editor Der Swagger Editor ist ein nützliches Online-Tool, um eine Übersicht über alle vorhandenen Befehle mit ihren zugehörigen Optionen zu erhalten und die Syntax von Befehlen für die Übertragung über die REST-Schnittstelle zu ermitteln. Es erfordert keine Installation. Eine detaillierte Beschreibung der Kommunikation mit der REST-Schnittstelle der icom Data Suite mit dem Swagger-Editor folgt an dieser Stelle zu einem späteren Zeitpunkt. Informationen zur Kommunikation mit der REST-Schnittstelle des Routers mit dem Swagger-Editor finden Sie [in diesem Configuration Guide](/kb/docs/de/working-with-the-rest-interface-de). ## 3. Fehlersuche - Bei Problemen mit der cURL-Syntax ist es hilfreich, die Option `-v` (verbose) zu verwenden, um die Fehlersuche zu vereinfachen. - Wird beim Ausführen eines aus dem Swagger-Editor kopierten cURL-Befehls ein Fehler im Zusammenhang mit einer nicht vertrauenswürdigen Zertifizierungskette angezeigt, wurde möglicherweise vergessen, die cURL-Option `-k` an den Befehl anzuhängen, welche eine Verifizierung des Zertifikats verhindert. - Je nach Betriebssystem kann es sein, dass der im Swagger-Editor erzeugte cURL-Befehl im Terminal nicht direkt verarbeitet werden kann. Dann ist er wir folgt anzupassen: - Befehl in Text-Editor kopieren - Apostrophe um den cURL-Befehl (z.B. GET) entfernen - Apostrophe um die Parameter durch Anführungszeichen ersetzen - Zeilenumbrüche entfernen - Unnötige Leerzeichen entfernen - Unnötige Backslash (\) entfernen