--- title: "Arbeiten mit der REST-Schnittstelle - icom OS Router" slug: "working-with-the-rest-interface-de" updated: 2025-07-17T08:20:40Z published: 2025-07-17T08:20:40Z canonical: "docs.insys-icom.com/working-with-the-rest-interface-de" --- > ## 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 OS Router REST steht für Representational State Transfer und stellt eine Schnittstelle für Konfiguration, Statusabfrage und Ausführung manueller Aktionen des Routers über das HTTP- und HTTPS-Protokoll zur Verfügung. > [!NOTE] > **Bitte beachten Sie!** > > Dieser Configuration Guide gilt ab der icom OS Firmware-Version 5.2 mit der neuen REST-API-Version 2.0. Aktualisieren Sie Ihren Router wenn dieser über eine frühere Firmware-Version verfügt. Die [HTTP(S)-REST-Schnittstelle](/kb/docs/de/rest-interface-de) erlaubt es, den Router 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**. Dies soll Ihnen vermitteln, wie Sie die erforderliche Syntax für Befehl und übermittelten Konfigurationsinformationen (Payload) mithilfe verschiedener Tools ermitteln und an den Router übertragen. Der Configuration Guide basiert auf einem Router in Werkseinstellungen nach Inbetriebnahme mit dem Schnellstart-Assistenten. Bei individuellen Konfigurationen kann die Beschreibung hinsichtlich Profilen, Adressen usw. abweichen. 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 für die INSYS-Router verfügbare **icom Data Suite** verfügt ebenso über eine REST-Schnittstelle. Der Umgang damit erfolgt analog zur hier beschriebenen REST-Schnittstelle des Routers und ist in diesem [Configuration Guide](/kb/docs/de/working-with-the-ids-rest-interface-en) beschrieben. > [!NOTE] > **Bitte beachten Sie!** > > Die Dokumentation der REST API enthält sämtliche Befehle, die in den verschiedenen Konfigurationen und Ausstattungsvarianten des Routers verfügbar sind. Nicht alle enthaltenen Befehle werden von Ihrem Router unterstützt. Router 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 des Routers - Hinzufügen eines neuen Benutzers - Ändern der Konfiguration dieses Benutzers - Löschen des neu hinzugefügten Benutzers - Manuelles Ausführen von Aktionen ## 2. Lösung Die gesamte Dokumentation der REST API wird in Form einer JSON-Datei gemäß der OpenAPI-Spezifikation 3.0 vom Router 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 Postman an den Router übermittelt. Stellen Sie sicher, dass Sie Zugriff auf das Web-Interface des Routers haben. ### 2.1. Aktivieren der REST-Schnittstelle und Herunterladen der REST API-Dokumentation Der Zugriff auf die REST-Schnittstelle über HTTPS ist in den Standardeinstellungen des Routers bereits aktiviert. 1. Öffnen Sie die Bedienoberfläche des Routers: [https://insys.icom](https://insys.icom) 2. Aktivieren Sie im Menü *Administration* → *Konfigurationszugriff* im Abschnitt *Web-/REST-Interface* die Checkbox *HTTPS aktivieren* und klicken Sie auf SPEICHERN. ![cg de m3 rest interface v2 01](https://docs.insys-icom.de/assets/cg_de_m3_rest_interface_v2_01.png) 3. Klicken Sie im Menü ![view dashboard outline](https://docs.insys-icom.de/assets/icons/view-dashboard-outline.png) *Administration* → *Konfigurationszugriff* auf *REST API Dokumentation (OpenAPI als JSON)* und laden Sie die REST API-Dokumentation auf den Rechner herunter. ![cg de m3 rest interface v2 01a](https://docs.insys-icom.de/assets/cg_de_m3_rest_interface_v2_01a.png) 4. Klicken sie auf PROFIL AKTIVIEREN . In den Standardeinstellungen des Routers ist die Firewall-Ausnahmeregel **Local access to webinterface via HTTPS** bereits vorhanden und konfiguriert. Diese erlaubt bei aktivierter Firewall den Zugriff auf die REST-Schnittstelle. Sie muss nur angepasst werden, wenn der entsprechende Port verändert wurde. Die Firewall-Regeln werden im Menü *Netzwerk* → *Firewall / NAT* konfiguriert. ### 2.2. Ermitteln der REST-Syntax und Übertragen der Konfigurationsbefehle an den Router Ein besonders bequemer Weg hierfür sind REST API-Tools wie Postman und der Swagger Editor. #### 2.2.1. Authentifizierung Die Authentifizierung erfolgt über Access- und Refresh-Tokens. Zum Erhalt der Tokens muss ein Post-Request gestellt werden, bei dem die Authentifizierung über eine Benutzername/Passwort-Kombination erfolgt, die im Menü *Administration* → *Benutzer* verwaltet wird. Mit dem daraufhin erhaltenen Access-Token im Authorization-Header wird die weitere Kommunikation über die REST-Schnittstelle authentifiziert. Mit dem Ablauf der Gültigkeit des Access-Tokens (5 Minuten) muss ein weiterer POST-Request mit dem Refresh-Token im Authorization-Header gestellt werden, um neue Access- und Refresh-Tokens für die weitere Kommunikation zu erhalten. Das Refresh-Token kann nur einmal zur Anfrage neuer Tokens verwendet werden und seine Gültigkeit ist identisch mit der im Menü *Administration* → *Konfigurationszugriff* im Abschnitt *Web/-REST-Interface* eingestellten Zeit für das *Auto-Logout bei Inaktivität*. Ein Abmelden von der REST-Schnittstelle erfolgt mit einem POST-Request, bei dem beide Tokens im Authorization-Header verwendet werden können. Die Tokens verlieren ihre Gültigkeit mit der Abmeldung, deren Ablauf oder einem Neustart des Routers. Beispiel für die Anfrage zum Erhalt der Tokens: `POST /api/v2_0/auth/login` Im Body der Anfrage werden Benutzername (hier **insys**) und Passwort (hier **icom**) übergeben. ```plaintext {  "username" : "insys",  "password" : "icom" } ``` Darauf sind folgende Antworten möglich: `400 Bad Request` → Body ist nicht korrekt `401 Unauthorized` → Zugangsdaten sind nicht korrekt `200 OK` → mit Rückgabe des folgenden Body (der die angefragten Tokens enthält): ```plaintext {  "access" : "",  "refresh" : "" } ``` Beispiel für die Anfrage zum Erneuern der Tokens: `POST /api/v2_0/auth/refresh` (das Refresh-Token muss sich im Authorization-Header befinden) Darauf sind folgende Antworten möglich: `401 Unauthorized` → Refresh-Token ist nicht korrekt `200 OK` → mit Rückgabe des folgenden Body (der die neuen Tokens enthält): ```plaintext {  "access" : "",  "refresh" : "" } ``` Beispiel für die Anfrage zum Abmelden von der Sitzung: `POST /api/v2_0/auth/logout` (eines der beiden Tokens muss sich im Authorization-Header befinden) Darauf sind folgende Antworten möglich: `401 Unauthorized` → Token ist nicht korrekt `200 OK` #### 2.2.2. Postman Die Postman-App ist ein nützliches Tool, um mit dem Router über die REST-Schnittstelle zu kommunizieren. Im Folgenden wird beschrieben, wie Sie in der Postman-App die REST API-Dokumentation des Routers importieren, die Access-Tokens für die REST-Schnittstelle anfordern und hinterlegen sowie die Umgebungsvariablen für die Kommunikation mit dem Router ü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. Markieren Sie die Option *Postman Collection* und klicken Sie auf die Schaltfläche *Import*. ![cg en m3 rest interface pm v2 01](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_01.png) Die Dokumentation der REST API des Routers wird als Sammlung (Collection) angezeigt. 5. Markieren Sie die neue Sammlung, wechseln Sie im rechten Feld auf die Registerkarte *Variables* und überprüfen Sie die hinterlegten Variablen für Protokoll (HTTP oder HTTPS), IP-Adresse des Routers, Port für den HTTP-/HTTPS-Zugang und die URL inkl. dem Pfad. Mit der oben importierten REST API-Dokumentation werden hier die Standardwerte des Routers übergeben. Wurden diese geändert, müssen Sie hier angepasst und gespeichert werden. ![cg en m3 rest interface pm v2 02](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_02.png) 6. Navigieren sie in der Sammlung *icom OS - REST API* zu *auth* → *login* und klicken sie auf den Befehl **POST**. 7. Wechseln Sie auf die Registerkarte *Body*, passen Sie die Variablen *username* und *password* an (wie für die Anmeldung an der Benutzeroberfläche des Routers, hier **insys** und **icom**) an und klicken Sie auf die Schaltfläche *Send*, um den POST-Befehl an den Router 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 beiden Tokens für die Authentifizierung. ![cg en m3 rest interface pm v2 03](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_03.png) 8. Kopieren Sie das Access-Token in die Zwischenablage. ![cg en m3 rest interface pm v2 04](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_04.png) 9. Fahren Sie über die neue Sammlung, klicken Sie auf *View more actions* und wählen Sie *Edit*. 10. Wechseln Sie im rechten Feld auf die Registerkarte *Authorization*, wählen Sie den *Type* **Bearer Token** und kopieren Sie das Access-Token aus der Zwischenablage in das Feld *Token*. ![cg en m3 rest interface pm v2 05](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_05.png) 11. Klicken Sie auf *Save Collection*, um das Token in der Sammlung zu hinterlegen. ![cg en m3 rest interface pm v2 06](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_06.png) Damit ist das Access-Token in der Sammlung hinterlegt und wird bei jeder folgenden Anfrage in den Authorization-Header der Anfrage eingefügt. > [!NOTE] > Begrenzte Gültigkeit des Access-Tokens! > > Achten Sie darauf, dass das Access-Token nur eine Gültigkeit von 5 Minuten hat und nach deren Ablauf ein neues Access-Token mit Hilfe des Refresh-Tokens angefordert werden muss. Dazu muss das Refresh-Token wie oben beschrieben als Token im HTTP-Befehl `POST /api/v2_0/auth/refresh` auf der Registerkarte *Authorization* hinterlegt und ein neues Token-Paar angefordert werden. Das dabei neu übermittelte Access-Token muss dann wieder wie oben beschrieben als Token in der Sammlung hinterlegt werden. Alternativ ist es auch möglich, einfach ein neues Access-Token wie oben beschrieben mit `POST /api/v2_0/auth/login` anzufordern und sich neu anzumelden. ![cg en m3 rest interface pm v2 07](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_07.png) ##### 2.2.2.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 OS - REST API* zu *configuration* → *administration* → *users* und klicken sie auf den Befehl **GET**. 2. Deaktivieren Sie auf der Registerkarte *Params* die Checkboxen für *profile*, *append_scheme*, *return_size* und *filter*. 3. Klicken Sie auf die Schaltfläche *Send*, um den GET-Befehl an den Router 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 des Routers. Vergleichen Sie dazu die Konfiguration im Web-Interface des Routers im Menü *Administration* auf der Seite *Benutzer*. ![cg en m3 rest interface pm v2 08](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_08.png) ![cg de m3 rest interface v2 02](https://docs.insys-icom.de/assets/cg_de_m3_rest_interface_v2_02.png) ##### 2.2.2.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 OS - 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": "Startup_Profile",    "activate": "1"  },  "config": {    "list": [      {        "active": "1",        "username": "CGTestUser",        "password": "icom",        "group": "read"      }    ]  } } ``` 1. Klicken Sie auf die Schaltfläche *Send*, um den POST-Befehl an den Router zu senden. Mit diesem Befehl wird ein neuer **aktiver** Benutzer mit dem Benutzernamen **CGTestUser**, dem Passwort **icom** und der Benutzergruppe **Lesen** dem Profil **Startup_Profile** hinzugefügt, das anschließend 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 m3 rest interface pm v2 09](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_09.png) Vergleichen Sie dazu die Konfiguration im Web-Interface des Routers im Menü *Administration* auf der Seite *Benutzer* mit dem neu hinzugefügten Benutzer. > [!NOTE] > Bitte beachten Sie! > > Um das Hinzufügen zu sehen, muss das laufende Profil im Router auch das Profil sein, zu dem der Benutzer hinzugefügt wurde, hier **Startup_Profile**. ![cg de m3 rest interface v2 03](https://docs.insys-icom.de/assets/cg_de_m3_rest_interface_v2_03.png) ##### 2.2.2.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. Der zu ändernde Benutzer wird über die Listen-ID **list_uid** identifiziert. Die Listen-ID wird beim Abfragen oder Hinzufügen des Benutzers angezeigt. 1. Navigieren sie in der Sammlung *icom OS - 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. 3. Ersetzen Sie die Listen-ID **list_uid** mit der ID, die beim Hinzufügen des Benutzers oben zurückgegeben wurde. ```plaintext {  "profile": {    "name": "Startup_Profile",    "activate": "0"  },  "config": {    "list": [      {        "group": "readwrite",        "index": "user2",        "list_uid": ""      }    ]  } } ``` 1. Klicken Sie auf die Schaltfläche *Send*, um den PUT-Befehl an den Router zu senden. Mit diesem Befehl wird für den Benutzer mit der entsprechenden Listen-ID **list_uid** im Profil **Startup_Profile** die Benutzergruppe auf **Lesen/Schreiben** gesetzt. Damit wird die Benutzergruppe des oben hinzugefügten Benutzers geändert. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **200 OK**. ![cg en m3 rest interface pm v2 10](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_10.png) Vergleichen Sie dazu die Konfiguration im Web-Interface des Routers im Menü *Administration* auf der Seite *Benutzer* mit der geänderten Benutzergruppe. ![cg de m3 rest interface v2 04](https://docs.insys-icom.de/assets/cg_de_m3_rest_interface_v2_04.png) ##### 2.2.2.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 OS - REST API* zu *configuration* → *administration* → *users* und klicken sie auf den Befehl **DEL**. 2. Deaktivieren Sie auf der Registerkarte *Params* unter *Query Params* den Abfrageparameter *delete*. 3. Tragen Sie für den Abfrageparameter *profile* den Wert **Startup_Profile** ein. Damit werden alle Benutzer, die den Filterkriterien entsprechen, aus dem Profil **Startup_Profile** gelöscht. 4. 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:Your title goes here > > "p" : "zu filternder Parameter" > > "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" 5. Klicken Sie auf die Schaltfläche *Send*, um den DELETE-Befehl an den Router zu senden. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **200 OK**. ![cg en m3 rest interface pm v2 11](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_11.png) Vergleichen Sie dazu die Konfiguration im Web-Interface des Routers im Menü *Administration* auf der Seite *Benutzer* mit dem nun wieder gelöschten Benutzer. ![cg de m3 rest interface v2 02](https://docs.insys-icom.de/assets/cg_de_m3_rest_interface_v2_02.png) ##### 2.2.2.5. Manuelles Ausführen von Aktionen Der Router ermöglicht das Ausführen einer Vielzahl von Aktionen, wie Synchronisierung mit einem Zeit-Server, Neustart, Meldungsversand oder das Setzen eines Ausgangs. Aktionen werden bei Eintreten eines Ereignisses ausgelöst, können aber auch manuell ausgelöst werden. Im vorliegenden Beispiel soll die **Info**-LED am Router manuell aktiviert werden. Der erforderliche HTTP-Befehl zum manuellen Auslösen von Aktionen ist **POST**. 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](/kb/docs/de/rest-interface-de#debug) sowie [Ermitteln der Befehls-Syntax für CLI und REST-Schnittstelle](/kb/docs/de/command-reference-de) in der Online-Hilfe des Routers. 1. Navigieren sie in der Sammlung *icom OS - 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" : "info_led",        "options" : {            "info_led" : "on"        }    } } ``` 1. Klicken Sie auf die Schaltfläche *Send*, um den POST-Befehl an den Router zu senden. Mit diesem Befehl wird die **Info**-LED am Router aktiviert. Analog dazu wird sie mit dem Wert **off** für den Parameter **info_led** deaktiviert. Die Antwort erscheint im unteren Teil des Fensters der Postman-App im JSON-Format mit dem Status-Code **201 Created**. ![cg en m3 rest interface pm v2 12](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_12.png) Beobachten Sie dazu auch die LED am Router. #### 2.2.3. 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. Er erfordert keine Installation. > [!CAUTION] > Bitte beachten Sie! > > Bis einschließlich Firmware-Version 8.7 war es möglich, mit dem Swagger Editor auch auf die Konfiguration des Routers zuzugreifen und diese zu bearbeiten. Maßnahmen zur Erhöhung der Sicherheit unserer Router verhindern nun diese Möglichkeit. Sie können den Swagger Editor aber weiterhin verwenden, 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. Für Zugriffe auf den Router empfehlen wir die Verwendung von [Postman](/kb/docs/de/working-with-the-rest-interface-de#222-postman), wie oben beschrieben. ##### 2.2.3.1. Laden der REST API-Dokumentation 1. Öffnen Sie den [Swagger Editor](https://editor.swagger.io) in einem Browser. 2. Klicken Sie im Swagger Editor auf *File* → *Import file* und öffnen Sie die oben heruntergeladene REST API-Dokumentation. ![cg en m3 rest interface se v2 01](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_se_v2_01.png) Damit haben Sie Zugriff auf die Dokumentation der REST API. Im linken Bereich finden Sie die Dokumentation im JSON-Format und im rechten Bereich wird diese übersichtlich lesbar nach den einzelnen Befehlen aufgeschlüsselt dargestellt. Die Reihenfolge der Befehle entspricht der Reihenfolge der Menüs im Web-Interface des Routers. Sie enthält sämtliche Befehle, die in den verschiedenen Konfigurationen und Ausstattungsvarianten des Routers verfügbar sind. Nicht alle enthaltenen Befehle werden von Ihrem Router unterstützt. ## 3. Weitere hilfreiche Informationen rund um die REST-Schnittstelle ### 3.1. Die verschiedenen Endpunkte der REST-Schnittstelle Die Endpunkte helfen dabei, die verschiedenen Ressourcen der REST-Schnittstelle zu kategorisieren und organisieren. Für den Zugriff auf die Ressourcen der API sind verschiedene Endpunkte vorhanden. ![cg en m3 rest interface pm v2 13](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_13.png) #### 3.1.1. Endpunkt *auth* Über den Endpunkt **auth** wird auf die Ressourcen zur Autorisierung an der REST-Schnittstelle zugegriffen. Dies erfolgt durch **POST**-Anfragen. Dies sind beispielsweise: - **/auth/login** zur Anforderung der Tokens zur Authentifizierung - **/auth/refresh** zur Anforderung der Refresh-Tokens zur Erneuerung der Authentifizierung - **/auth/logout** zur Anforderung einer Aufhebung der Authentifizierung (Abmeldung) #### 3.1.2. Endpunkt *status* Über den Endpunkt **status** wird auf die Ressourcen zur Abfrage der Zustandswerte des Routers zugegriffen. Dies erfolgt durch **GET**-Anfragen. Dies sind beispielsweise: - **/status/device_info** zur Anforderung einer Übersicht über die Geräteinformationen des Routers ![cg en m3 rest interface pm v2 14](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_14.png) - **/status/sysdetail/system** zur Anforderung einer Übersicht über die Systemdetails des Routers ![cg en m3 rest interface pm v2 15](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_15.png) - **/status/sysdetail/container** zur Anforderung einer Übersicht über die auf dem Router laufenden Container ![cg en m3 rest interface pm v2 16](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_pm_v2_16.png) #### 3.1.3. Endpunkt *configuration* Über den Endpunkt **configuration** wird auf die Ressourcen zur Änderung Parameter für die Konfiguration des Routers zugegriffen. Dies erfolgt durch die Anfragen: - **GET** - Abfragen von Parametern - **PUT** - Setzen von Parametern - **POST** - Ändern von Parametern - **DEL** - Löschen von Parametern Dies sind beispielsweise: - **/configuration/wan/wans** zur Konfiguration der WAN-Ketten - **/configuration/netfilter/ip_filter** zur Konfiguration der Firewall - **/configuration/administration/cli** zur Konfiguration des Zugriffs auf die CLI #### 3.1.4. Endpunkt *profiles* Über den Endpunkt **profiles** wird auf die Ressourcen zum Umgang mit den Profilen des Routers zugegriffen. Dies erfolgt durch die Anfragen: - **GET** - Abfragen von Profilen - **PUT** - Aktivieren und Umbenennen von Profilen sowie Setzen des Profil-Modus oder Speichern des laufenden Profils im permanenten Profil-Modus - **POST** - Ändern von Profilen - **DEL** - Löschen von Profilen Dies sind beispielsweise: - **/profiles** zur Anforderung einer Profilübersicht oder zum Anlegen oder Löschen von Profilen - **/profiles/activate** zur Anforderung einer Aktivierung eines Profils - **/profiles/profile_mode** zur Anforderung einer Umschaltung des Profil-Modus #### 3.1.5. Endpunkt *upload* Über den Endpunkt **upload** wird auf die Ressourcen zum Hochladen, Analysieren und Ausführen von Dateien auf den/dem Router zugegriffen. Dies erfolgt durch **POST**-Anfragen. Dies sind beispielsweise: - **/upload/analyze** zum Hochladen und zur Anforderung einer Analyse der hochgeladenen Datei - **/upload/reanalyze** zur Anforderung einer Analyse einer hochgeladenen Datei - **/upload/perform** zur Anforderung einer Ausführung einer hochgeladenen Datei #### 3.1.6. Endpunkt *download* Über den Endpunkt **download** wird auf die Ressourcen zum Herunterladen von Dateien auf dem Router zugegriffen. Dies erfolgt durch **GET**-Anfragen. Dies sind beispielsweise: - **/download/log** zum Herunterladen von Log-Dateien auf dem Router - **/download/certificates/public_keys** zum Herunterladen von öffentlichen Schlüsseln auf dem Router #### 3.1.7. Endpunkt *firmware* Über den Endpunkt **firmware** wird auf die Ressource zum Umgang mit Firmware-Dateien zugegriffen. Dies erfolgt durch die Anfragen: - **GET** - Abfragen von Firmware-Dateien auf dem Router - **PUT** - Hochladen von Firmware-Dateien auf den Router - **DEL** - Löschen von Firmware-Dateien auf dem Router Dies ist beispielsweise: - **/firmware** zum Abfragen, Hochladen oder Löschen von Firmware-Dateien #### 3.1.8. Endpunkt *container* Über den Endpunkt **container** wird auf die Ressourcen zum Umgang mit Container auf dem Router zugegriffen. Dies erfolgt durch die Anfragen: - **GET** - Abfragen von Containern - **PUT** - Aktivieren von Containern - **POST** - Ändern von Containern - **DEL** - Löschen von Containern Dies sind beispielsweise: - **/container/container** zum Abfragen, Aktivieren, Ändern und Löschen von Containern - **/container/licenses** zum Abfragen und Löschen von Lizenzen für Container #### 3.1.9. Endpunkt *operation* Über den Endpunkt **operation** wird auf die Ressource zum Ausführen manueller Aktionen auf dem Router zugegriffen. Dies erfolgt durch **POST**-Anfragen. Dies ist beispielsweise: - **/operation** zum Ausführen manueller Aktionen #### 3.1.10. Endpunkt *reboot* Über den Endpunkt **reboot** wird auf die Ressource zum Ausführen eines Neustarts des Routers zugegriffen. Dies erfolgt durch **POST**-Anfragen. Dies ist beispielsweise: - **/reboot** zum Neustarten des Routers #### 3.1.11. Endpunkt *reset* Über den Endpunkt **reset** wird auf die Ressource zum Ausführen einer Zurücksetzung des Routers zugegriffen. Dies erfolgt durch **POST**-Anfragen. Dies ist beispielsweise: - **/reset** zum Zurücksetzen ausgewählter Datensätze des Routers auf Werkseinstellungen #### 3.1.12. Endpunkt *secure_reset* Über den Endpunkt **secure_reset** wird auf die Ressource zum Ausführen einer sicheren Löschung aller Dateien auf dem Router zugegriffen. Dies erfolgt durch **POST**-Anfragen. Dies ist beispielsweise: - **/secure_reset** zum sicheren Löschen aller Dateien auf dem Router ### 3.2. Die verschiedenen Operationen der REST-Schnittstelle (manuelle Aktionen) Manuelle Aktionen können über die REST-Schnittstelle mit Hilfe einer **operation** ausgeführt werden. Je nach Router stehen einer Reihe manueller Aktionen zur Verfügung, wie das Setzen eines Ausgangs, das Ausführen eines Neustarts oder das Versenden einer Nachricht. Eine Übersicht über die verfügbaren manuellen Aktionen erhalten Sie, wenn Sie die Dokumentation der REST-API (wie im Abschnitt [Herunterladen der REST API-Dokumentation](/kb/docs/de/working-with-the-rest-interface-de#21-aktivieren-der-restschnittstelle-und-herunterladen-der-rest-apidokumentation) beschrieben) in einem Browser öffnen. Im Abschnitt *components* → *schemas* finden Sie bei *operation* sämtliche manuellen Aktionen, die über die REST-Schnittstelle ausgeführt werden können (dabei sind nicht alle dieser Aktionen auf jedem Router verfügbar). ![cg en m3 rest interface v2 05](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_v2_05.png)Hier können Sie auch die für jede Aktion erforderlichen Parameter und deren mögliche Werte ermitteln, die im Request-Body des entsprechenden **POST**-Befehls im JSON-Format übergeben werden müssen, um die manuelle Aktion auszuführen. ![cg en m3 rest interface v2 06](https://docs.insys-icom.de/assets/cg_en_m3_rest_interface_v2_06.png)Mit dem **POST**-Befehl auf den Endpunkt **/api/v2_0/operation** und folgendem Request-Body wird beispielsweise der Ausgang 3.1 des Routers umgeschaltet. ```plaintext {    "method" : "manual_action",    "params" : {        "type" : "output",        "options" : {            "output" : "3.1",            "change" : "toggle"        }    } } ``` Als Antwort wird nur der Status-Code **201 Created** zurückgegeben. Es erfolgt keine Rückgabe in Form einer Payload. ### 3.3. Beispielhafte Anwendungsfälle #### 3.3.1. Installieren eines einzelnen Zertifikats aus einer Zertifikatsdatei Zertifikatsdateien enthalten oft mehrere Dateien, z.B. ein Zertifikat, einen privaten Schlüssel und ein CA-Zertifikat. Um nun beispielsweise nur das Zertifikat auf den Router zu laden, gehen Sie wie folgt vor. - Laden Sie die Datei mit einem **POST**-Befehl auf den Endpunkt **/api/v2_0/upload/analyze** hoch. Dabei wird die Datei in einem temporären Verzeichnis gespeichert und anschließend analysiert. Der Inhalt der Datei wird im Response-Body zurückgegeben: ```plaintext {    "filename": "openvpnclient1.p12",    "identifier": "419781432b",    "content": [        {            "entry": 0,            "name": "Certificate",            "type": "Cert - Certificate",            "valid": true        },        {            "entry": 1,            "name": "CA Certificate",            "type": "Cert - CA Certificate",            "valid": true        },        {            "entry": 2,            "name": "Private Key",            "type": "Cert - Private Key",            "valid": true        }    ] } ``` Hier sehen Sie, dass die Datei drei Einträge (entries) enthält, ein Zertifikat (0), ein CA-Zertifikat (1) und einen privaten Schlüssel (2). Der Vorgang wird durch den **identifier** eindeutig identifiziert. Das CA-Zertifikat **1** des Vorgangs **419781432b** soll nun im Profil **Profile_1** gespeichert werden. - Übergeben Sie mit dem **POST**-Befehl auf den Endpunkt **/api/v2_0/upload/perform** den Request-Body: ```plaintext {    "identifier": "419781432b",    "entries": [        {            "entry": 1,            "action": "store"        }    ],    "profile": "Profile_1" } ``` Im Response-Body wird der Name zurückgegeben, unter dem das CA-Zertifikat in diesem Profil gespeichert wurde: ```plaintext {    "filename": "openvpnclient1.p12",    "identifier": "ba6b89c535",    "content": [        {            "entry": 1,            "name": "ca_cert1",            "type": "Cert - CA Certificate",            "result": "done"        }    ] } ``` ## 4. Fehlersuche - Antwortet das Gerät auf einen Befehl mit **401 Unauthorized**, ist die Gültigkeitsdauer des Tokens abgelaufen oder es wurde ein falscher Token hinterlegt. Standard-IP-Adresse: https://192.168.1.1; Anmeldung je nach Konfiguration; Voreinstellung bei älteren Firmware-Versionen: *Benutzername*: **insys**, *Kennwort*: **icom**