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.

Dieser Configuration Guide gilt ab der icom OS Firmware-Version 5.2 mit der neuen REST-API-Version 2.0. Verwenden Sie den bisherigen Configuration Guide wenn Ihr Router über eine frühere Firmware-Version verfügt. Die Benutzerführung wird anhand der neuen Benutzerschnittstelle ab icom OS 6.0 beschrieben.

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.

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.

Die für die INSYS-Router verfügbare icom Data Suite verfügt ebenso über eine REST-Schnittstelle. Der Umgang damit erfolgt analog zur in diesem Configuration Guide 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
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 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

Der Zugriff auf die REST-Schnittstelle über HTTPS ist in den Standardeinstellungen des Routers bereits aktiviert.

Öffnen Sie die Bedienoberfläche des Routers in einem Browser: insys.icom ^[1]
Aktivieren Sie im Menü Administration → Konfigurationszugriff im Abschnitt Web-/REST-Interface die Checkbox HTTPS aktivieren und klicken Sie auf SPEICHERN .
Klicken Sie im Menü Administration → Konfigurationszugriff auf REST API Dokumentation (OpenAPI als JSON) und laden Sie die REST API-Dokumentation auf den Rechner herunter.
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. Konfigurationsbefehle können auch mithilfe von cURL aus einer Kommandozeile heraus erfolgen.

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.

{
  "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):

{
  "access" : "<Access-Token>",
  "refresh" : "<Refresh-Token>"
}

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):

{
  "access" : "<New-Access-Token>",
  "refresh" : "<New-Refresh-Token>"
}

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.

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.
Markieren Sie die Option Postman Collection und klicken Sie auf die Schaltfläche Import.

Die Dokumentation der REST API des Routers wird als Sammlung (Collection) angezeigt.
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.
Navigieren sie in der Sammlung icom OS - REST API zu auth → login und klicken sie auf den Befehl POST.
Wechseln Sie auf die Registerkarte Body, passen Sie die Variablen username und password an (hier insys und icom)^[2] 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.
Kopieren Sie das Access-Token in die Zwischenablage.
Fahren Sie über die neue Sammlung, klicken Sie auf View more actions und wählen Sie Edit.
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.
Klicken Sie auf Save Collection, um das Token in der Sammlung zu hinterlegen.

Damit ist das Access-Token in der Sammlung hinterlegt und wird bei jeder folgenden Anfrage in den Authorization-Header der Anfrage eingefügt.

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

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.

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

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.

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": "Startup_Profile",
    "activate": "1"
  },
  "config": {
    "list": [
      {
        "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 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

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 v2 03

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.

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.
Ersetzen Sie die Listen-ID list_uid mit der ID, die beim Hinzufügen des Benutzers oben zurückgegeben wurde.

{
  "profile": {
    "name": "Startup_Profile",
    "activate": "0"
  },
  "config": {
    "list": [
      {
        "group": "readwrite",
        "index": "user2",
        "list_uid": "<tragen Sie hier die im vorherigen Schritt übermittelte list_uid dieses Benutzers ein>"
      }
    ]
  }
}

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

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 v2 04

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.

Navigieren sie in der Sammlung icom OS - REST API zu configuration → administration → users und klicken sie auf den Befehl DEL.
Deaktivieren Sie auf der Registerkarte Params unter Query Params den Abfrageparameter delete.
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.
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 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"

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

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 v2 02

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 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 v2 12

Beobachten Sie dazu auch die LED am Router.

2.2.3. Swagger Editor

Der Swagger Editor ist ein nützliches Online-Tool, um mit dem Router über die REST-Schnittstelle zu kommunizieren sowie 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. Im Folgenden wird beschrieben, wie Sie im Swagger Editor 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. An einem Beispiel wird Ihnen gezeigt, wie Sie 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.
Navigieren sie im rechten Bereich des Swagger Editors zum Abschnitt Authorization und klicken sie dort unter auth/login 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 wenn erforderlich username und password an und klicken Sie auf Execute, um den Befehl auszuführen.

Die Antwort wird im Swagger-Editor im Abschnitt Responses unter Server Response im Feld Response body angezeigt.
Kopieren Sie den im Feld Response body angezeigten Access-Token.
Klicken Sie auf Authorize und fügen Sie den kopierten Access-Token ein:
Klicken Sie auf Authorize und dann auf Close.

Damit haben Sie den Access-Token im Swagger Editor hinterlegt. Er wird dann jeder folgenden Anfrage in den Authorization-Header der Anfrage oder den erzeugten cURL-Befehl eingefügt. Aus Sicherheitsgründen läuft die Gültigkeit des Access-Tokens allerdings nach fünf Minuten ab und obiger Vorgang muss wiederholt werden.

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.2.3.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, setzen Sie append_Scheme auf -- und klicken Sie auf Execute, um den Befehl auszuführen.

Die Antwort erscheint rechts im Swagger-Editor im Abschnitt Responses unter Server response mit dem Status-Code 200 OK und im Feld Response body im JSON-Format. Sie enthält die Benutzer-Konfiguration des Routers.
cg en m3 rest interface se v2 08

Im Folgenden sehen Sie, wie Sie den im Swagger-Editor erzeugten Befehl mit Hilfe eines Terminal-Programms an den Router übermitteln.

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 v2 02

2.2.3.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 auszuführen.

{
  "profile": {
    "name": "Startup_Profile",
    "activate": "1"
  },
  "config": {
    "list": [
      {
        "active": "1",
        "username": "CGTestUser",
        "password": "icom",
        "group": "read"
      }
    ]
  }
}

Damit 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 nicht aktiviert wird.

Die Antwort erscheint rechts im Swagger-Editor im Abschnitt Responses unter Server response mit dem Status-Code 201 Created und im Feld Response body im JSON-Format. Sie enthält die übertragene Konfiguration.
cg en m3 rest interface se v2 11

In der Antwort erscheint für diesen Benutzer auch der Parameter list_uid, der dem Benutzer eine eindeutige ID zuweist. Kopieren oder notieren Sie sich diese ID. Diese ID ist nötig, um im nächsten Schritt Änderungen an diesem Benutzer durchzuführen.

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 03

2.2.3.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 auszuführen; vergessen Sie dabei nicht, den individuellen Parameter list_uid für den oben angelegten Benutzer anzupassen.

{
  "profile": {
    "name": "Startup_Profile",
    "activate": "0"
  },
  "config": {
    "list": [
      {
        "index": "user2",
        "list_uid": "<tragen Sie hier die im vorherigen Schritt übermittelte list_uid dieses Benutzers ein>"
      }
    ]
  }
}

Die Antwort erscheint rechts im Swagger-Editor im Abschnitt Responses unter Server response mit dem Status-Code 200 OK und im Feld Response body im JSON-Format. Sie enthält die übertragene Konfiguration.
cg en m3 rest interface se v2 14

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

2.2.3.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 Startup_Profile ein. Damit werden alle Benutzer, die den Filterkriterien entsprechen, aus dem Profil Startup_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").

Setzen Sie den Abfrageparameter delete auf --.
Klicken Sie auf Execute, um den Befehl auszuführen.

Die Antwort erscheint rechts im Swagger-Editor im Abschnitt Responses unter Server response mit dem Status-Code 200 OK und im Feld Response body 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 dem nun wieder gelöschten Benutzer.
cg de m3 rest interface v2 02

2.2.3.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 auszuführen.

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

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 rechts im Swagger-Editor im Abschnitt Responses unter Server response mit dem Status-Code 201 Created.
cg en m3 rest interface se v2 20

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 v2 21

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

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
/status/sysdetail/system zur Anforderung einer Übersicht über die Systemdetails des Routers
/status/sysdetail/container zur Anforderung einer Übersicht über die auf dem Router laufenden Container

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 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 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 Mit dem POST-Befehl auf den Endpunkt /api/v2_0/operation und folgendem Request-Body wird beispielsweise der Ausgang 3.1 des Routers umgeschaltet.

{
    "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:

{
    "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:

{
    "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:

{
    "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.
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
Reagiert Swagger auf die Ausführung eines Befehls mit Failed to fetch, verhindert der Browser wahrscheinlich die Kommunikation mit dem Router, da er diesen als unsicher einstuft. Geben Sie zur Abhilfe die URL des Routers (192.168.1.1) in die Adressleiste des Browsers ein und klicken Sie dann auf der Seite, die über die unsichere Verbindung informiert auf Erweitert und Weiter zu 192.168.1.1 (unsicher) (Browser-abhängig), um für den Router eine Ausnahme im Browser zu hinterlegen.

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

Zurück zur Übersicht

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

2. Dies sind die Zugangsdaten, mit denen Sie sich auch auf der Benutzeroberfläche des Routers anmelden.

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