Arbeiten mit der REST-Schnittstelle

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.

Nutzen der REST-Schnittstelle: Die HTTP(S)-REST-Schnittstelle 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 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 den Router übertragen.

Die REST-Schnittstelle wird von sämtlichen INSYS-Routern mit icom OS ab Firmware 4.3 unterstützt. Die genannten Tools sind nur Beispiele und dienen als Leitfaden für den Umgang mit der REST-Schnittstelle mithilfe externer Tools.

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.

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

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 diesen Tools oder über einen cURL-Befehl 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

Web-Interface des Routers mit einem Browser aufrufen: 192.168.1.1 ^[1]
Im Menü Administration → REST-Interface die Checkbox REST-Interface via HTTPS aktivieren markieren und auf Einstellungen speichern klicken.
Auf REST API Dokumentation (OpenAPI als JSON) klicken und die REST API-Dokumentation auf den Rechner herunterladen.
Auf das blinkende Zahnrad in der Titelleiste () klicken, um das Profil zu aktivieren.

2.2. Anlegen einer Firewall-Regel

Wenn am Router eine Firewall aktiviert ist, muss eine Ausnahmeregel angelegt werden, welche den Zugriff auf die REST-Schnittstelle erlaubt.

Im Menü Netzfilter → IP-Filter eine neue Firewall-Regel hinzufügen () und diese bearbeiten ():
- Beschreibung: Local access to REST interface via HTTPS
- Paket-Richtung: INPUT
- IP-Version: verwendete IP-Version auswählen
- Protokoll: TCP
- Eingehendes Interface: alle Interfaces markieren, über die auf die REST-Schnittstelle zugegriffen werden soll
- Ziel-Port: 9091
Auf Einstellungen speichern klicken.
Auf das blinkende Zahnrad in der Titelleiste () klicken, um das Profil zu aktivieren.

2.3. 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. Konfigurationsbefehle können auch mithilfe von cURL auch aus einer Kommandozeile heraus erfolgen.

2.3.1. 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 Zugangsdaten für die REST-Schnittstelle hinterlegen und die Umgebungsvariablen für die Kommunikation mit dem Router überprüfen.

Laden Sie die Postman-App herunter und installieren Sie diese.
Öffnen Sie die Postman-App
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.
Wählen Sie Documentation unter Link this collection as und klicken Sie auf die Schaltfläche Import.
Klicken Sie auf die Schaltfläche Close um den Import abzuschließen.
Die Dokumentation der REST API des Routers wird als Sammlung (Collection) angezeigt.
Fahren Sie über die neue Sammlung, klicken Sie auf View more actions und wählen Sie Edit.
Wechseln Sie im Feld der icom OS - 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 des Routers mit Lese- und Schreibrechten angelegt sein.
Klicken Sie auf Save, um die Zugangsdaten in der Sammlung zu hinterlegen.
Wechseln Sie auf die Registerkarte Variables und überprüfen Sie die hinterlegten Variablen für Protokoll (HTTP oder HTTPS), IP-Adresse des Routers und Port für den HTTP-/HTTPS-Zugang. Mit der oben importierten REST API-Dokumentation werden hier die Standardwerte des Routers übergeben. Wurden diese geändert, müssen Sie hier angepasst werden. ^[2]

2.3.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.

Navigieren sie in der Sammlung icom OS - REST API zu configuration → administration → users und klicken sie auf den Befehl GET.
Deaktivieren Sie im Abschnitt Query Params die Checkboxen für profile, return_size und filter.
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 05
cg de m3 rest interface 02

2.3.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.

Navigieren sie in der Sammlung icom OS - REST API zu configuration → administration → users und klicken sie auf den Befehl POST.
Wechseln Sie auf die Registerkarte Body und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "active": "1",
        "username": "CGTestUser",
        "password": "icom",
        "group": "read"
      }
    ]
  }
}

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 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 m3 rest interface pm 06

Vergleichen Sie dazu die Konfiguration im Web-Interface des Routers im Menü Administration auf der Seite Benutzer mit dem neu hinzugefügten Benutzer. ^[3]
cg de m3 rest interface 03

2.3.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.

Navigieren sie in der Sammlung icom OS - REST API zu configuration → administration → users und klicken sie auf den Befehl PUT.
Wechseln Sie auf die Registerkarte Body und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "group": "readwrite",
        "index": "user2"
      }
    ]
  }
}

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 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 m3 rest interface pm 07

Vergleichen Sie dazu die Konfiguration im Web-Interface des Routers im Menü Administration auf der Seite Benutzer mit der geänderten Benutzergruppe. ^[3]
cg de m3 rest interface 04

2.3.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.

Navigieren sie in der Sammlung icom OS - REST API zu configuration → administration → users und klicken sie auf den Befehl DEL.
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.
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").

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"

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 08

Vergleichen Sie dazu die Konfiguration im Web-Interface des Routers im Menü Administration auf der Seite Benutzer mit dem nun wieder gelöschten Benutzer. ^[3]
cg de m3 rest interface 02

2.3.1.5. Manuelles Ausführen von Aktionen

Der Router ermöglich 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 sowie Ermitteln der Befehls-Syntax für CLI und REST-Schnittstelle in der Online-Hilfe des Routers.

Navigieren sie in der Sammlung icom OS - REST API zu operation und klicken sie auf den Befehl POST.
Wechseln Sie auf die Registerkarte Body und passen Sie die Nutzlast im JSON-Format wie folgt an oder kopieren Sie diese hinein.

{
    "method" : "manual_action",
    "params" : {
        "type" : "info_led",
        "options" : {
            "info_led" : "on"
        }
    }
}

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 09

Beobachten Sie dazu auch die LED am Router.

2.3.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. Im Folgenden wird beschrieben, wie Sie im Swagger Editor die REST API-Dokumentation des Routers importieren, die Syntax für einen Befehl ermitteln und den Befehl in einer Kommandozeile mittels cURL an den Router übertragen.

Öffnen Sie den Swagger Editor in einem Browser.
Klicken Sie im Swagger Editor auf File → Import file und öffnen Sie die oben heruntergeladene REST API-Dokumentation.
Klicken Sie auf Authorize und geben Sie Ihre Zugangsdaten ein:
- Username: insys (Voreinstellung)
- Password: icom (Voreinstellung)
Klicken Sie auf Authorize und dann auf Close.

Damit haben Sie Ihre Zugangsdaten im Swagger Editor hinterlegt. Sie werden dann verschlüsselt in die erzeugten cURL-Befehle integriert.

Im linken Bereich finden Sie die REST API-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.

2.3.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.

Navigieren sie im rechten Bereich des Swagger Editors zum Abschnitt Administration und klicken sie dort unter configuration/administration/users auf den Befehl GET, um die detaillierte Beschreibung des Befehls zu öffnen.
Klicken Sie auf Try it out, um den Befehl erzeugen zu können.
Löschen Sie die Vorgabewerte der möglichen Abfrageparameter profile und return_size und klicken Sie auf Execute, um den Befehl zu erzeugen.
Kopieren Sie den im Abschnitt Curl angezeigten Befehl.
Öffnen Sie ein Terminal-Fenster (unter Windows: → → Eingabeaufforderung), fügen sie den kopierten Befehl ein ^[4], hängen Sie die Option -k an den Befehl und drücken Sie die Eingabetaste. ^[5]

Die Antwort erscheint im Terminal-Fenster im JSON-Format. 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 de m3 rest interface 02

2.3.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.

Navigieren sie im rechten Bereich des Swagger Editors zum Abschnitt Administration und klicken sie dort unter /configuration/administration/users auf den Befehl POST, um die detaillierte Beschreibung des Befehls zu öffnen.
Klicken Sie auf Try it out, um den Befehl erzeugen zu können.
Passen Sie die Nutzlast im JSON-Format im Abschnitt Request body wie folgt an oder kopieren Sie diese hinein und klicken Sie auf Execute, um den Befehl zu erzeugen.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "active": "1",
        "username": "CGTestUser",
        "password": "icom",
        "group": "read"
      }
    ]
  }
}

Kopieren Sie den im Abschnitt Curl angezeigten Befehl.
Öffnen Sie ein Terminal-Fenster, fügen sie den kopierten Befehl ein ^[4], hängen Sie die Option -k an den Befehl und drücken Sie die Eingabetaste. ^[5]

Die Antwort erscheint im Terminal-Fenster im JSON-Format. Sie enthält die übertragene Konfiguration.

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 03

2.3.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.

Navigieren sie im rechten Bereich des Swagger Editors zum Abschnitt Administration und klicken sie dort unter /configuration/administration/users auf den Befehl PUT, um die detaillierte Beschreibung des Befehls zu öffnen.
Klicken Sie auf Try it out, um den Befehl erzeugen zu können.
Passen Sie die Nutzlast im JSON-Format im Abschnitt Request body wie folgt an oder kopieren Sie diese hinein und klicken Sie auf Execute, um den Befehl zu erzeugen.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "group": "readwrite",
        "index": "user2"
      }
    ]
  }
}

Kopieren Sie den im Abschnitt Curl angezeigten Befehl.
Öffnen Sie ein Terminal-Fenster, fügen sie den kopierten Befehl ein ^[4], hängen Sie die Option -k an den Befehl und drücken Sie die Eingabetaste. ^[5]

Es erscheint keine gesonderte Antwort im Terminal-Fenster.

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 04

2.3.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.

Navigieren sie im rechten Bereich des Swagger Editors zum Abschnitt Administration und klicken sie dort unter /configuration/administration/users auf den Befehl DELETE, um die detaillierte Beschreibung des Befehls zu öffnen.
Klicken Sie auf Try it out, um den Befehl erzeugen zu können.
Tragen Sie im Abschnitt Parameters für den Abfrageparameter profile den Wert Profile ein. Damit werden alle Benutzer, die den Filterkriterien entsprechen, aus dem Profil Profile gelöscht.
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").

Klicken Sie auf Execute, um den Befehl zu erzeugen.
Kopieren Sie den im Abschnitt Curl angezeigten Befehl.
Öffnen Sie ein Terminal-Fenster, fügen sie den kopierten Befehl ein ^[4], hängen Sie die Option -k an den Befehl und drücken Sie die Eingabetaste. ^[5]

Es erscheint keine gesonderte Antwort im Terminal-Fenster.

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 02

2.3.2.5. Manuelles Ausführen von Aktionen

Der erforderliche HTTP-Befehl zum manuellen Auslösen von Aktionen ist POST. Die Syntax des Befehls ist in der Dokumentation der REST API beschrieben.

Navigieren sie im rechten Bereich des Swagger Editors zum Abschnitt Operation und klicken sie dort unter /operation auf den Befehl POST, um die detaillierte Beschreibung des Befehls zu öffnen.
Klicken Sie auf Try it out, um den Befehl erzeugen zu können.
Passen Sie die Nutzlast im JSON-Format im Abschnitt Request body wie folgt an oder kopieren Sie diese hinein und klicken Sie auf Execute, um den Befehl zu erzeugen.

{
    "method" : "manual_action",
    "params" : {
        "type" : "info_led",
        "options" : {
            "info_led" : "on"
        }
    }
}

Kopieren Sie den im Abschnitt Curl angezeigten Befehl.
Öffnen Sie ein Terminal-Fenster, fügen sie den kopierten Befehl ein ^[4], hängen Sie die Option -k an den Befehl und drücken Sie die Eingabetaste. ^[5]

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.

Es erscheint keine gesonderte Antwort im Terminal-Fenster. Beobachten Sie dazu auch die LED am Router.

Die einzelnen Parameter zu den verschiedenen Aktionen finden sich in der REST API im Abschnitt Schemas im Swagger Editor.
cg en m3 rest interface se 17

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

Zurück zu den Configuration Guides für die icom OS Smart Devices

Zurück zur Übersicht

1. Anmeldung je nach Konfiguration; Voreinstellung bei älteren Firmware-Versionen: Benutzername: insys, Kennwort: icom

2. In einer frühen Version der REST API-Dokumentation (Firmware 4.3) ist der falsche Standard-Port für HTTPS eingetragen (9090 statt 9091) und muss hier geändert werden.

3. Um das Hinzufügen zu sehen, muss das laufende Profil im Router auch das Profil sein, zu dem der Benutzer hinzugefügt wurde, hier Profile

4. Möglicherweise muss der erzeugte cURL-Befehl angepasst werden; siehe Fehlersuche

5. Mit der cURL-Option -k wird eine Verifizierung des Zertifikats verhindert.