 |
Online-Hilfe |
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.
Folgende Befehle (HTTP-Methoden) stehen zum Bearbeiten der Ressourcen (Parameter bzw. Einträge) zur Verfügung:
- GET: Auslesen einer Ressource
- POST: Hinzufügen einer Ressource
- PUT: Ändern einer Ressource
- DELETE: Löschen einer Ressource
Dokumentation der REST API
Die REST API (Programmierschnittstelle) ist in einer JSON-Datei gemäß der OpenAPI-Spezifikation 3.0 dokumentiert. Die Datei kann im Menü Administration auf der Seite REST-Interface heruntergeladen werden. Sie enthält sämtliche Befehle, die in den verscheidenen Konfigurationen und Ausstattungsvarianten des Routers verfügbar sind. Nicht alle enthaltenen Befehle werden von Ihrem Router unterstützt.
Syntax
Die Syntax der verfügbaren Befehle lässt sich leicht über die REST API-Dokumentationsdatei ermitteln, indem diese mit einem OpenAPI-Werkzeug, wie Swagger oder Postman, geöffnet wird.
Siehe dazu die Seite Befehlsreferenz.
Alternativ lässt sie sich auch über die Autovervollständigung im CLI herausfinden.
Siehe dieses Beispiel für die Vorgehensweise zum Ermitteln der Befehls-Syntax.
Aktivieren der REST-Schnittstelle
Bevor ein Zugriff auf die REST-Schnittstelle des Routers über HTTP oder HTTPS möglich ist, muss dies im Menü Administration auf der Seite REST-Interface entsprechend konfiguriert werden. Dazu muss der Zugang über HTTP und/oder HTTPS aktiviert werden und bei aktiver Firewall eine entsprechende Ausnahmeregel vorhanden und aktiv sein. Die Standard-Ports (9090 für HTTP und 9091 für HTTPS) können angepasst werden. Das unverschlüsselte HTTP-Protokoll sollte nur verwendet werden, wenn die Verbindung anderweitig verschlüsselt ist, z.B. durch ein VPN.
Adressierung
Die Adressierung erfolgt über die IP-Adresse des routers, den Port für den REST-Zugriff und den Pfad zu den Parametern.
Der Pfad zu den Parametern ist hier genauso in Sektionen strukturiert wie im CLI.
Die Adressierung für die Parameter der REST-Schnittstelle in einem Router mit der IP-Adresse 192.168.1.10 und den HTTPS-Port ist zum Beispiel:
192.168.1.10:9091/configuration/administration/rest
Der Pfad beginnt immer mit einem bestimmten Verzeichnis, z.B. /configuration/ für Konfigurationsparameter, darauf folgen die entsprechenden Sektionen.
Response-Codes (Antwortcodes)
Sämtliche REST-Befehle werden mit HTTP-Statuscodes beantwortet. Für die hier beschriebenen Parameter werden folgende Codes bei einer erfolgreichen Übermittlung des REST-Befehls zurückgegeben:
- GET: 200 OK
- POST: 201 CREATED
- PUT: 200 OK
- DELETE: 200 OK
Konfiguration
Zum Auslesen oder Ändern der Konfiguration stehen die Befehle (HTTP-Methoden) GET, POST, PUT und DELETE zur Verfügung. Für Konfigurationsparameter beginnt der Pfad immer mit /configuration/.
Auslesen von Parametern (GET)
Parameter werden mit der HTTP-Methode GET ausgelesen.
Beispiel für das Auslesen der Parameter der REST-Schnittstelle:
GET /configuration/administration/rest
Als Antwort werden sämtliche Parameter mit ihrer Einstellung im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "1",
"https_active": "1",
"http_port": "9090",
"https_port": "9091",
"https_cert": "device_cert",
"https_key": "device_key",
"log_requests": "0"
}
}
Der erste Abschnitt der Antwort referenziert das Profil, der zweite die Konfiguration mit den einzelnen Parametern.
Spezifizieren des Profils im GET-Befehl
Ohne eine Angabe bezieht sich der GET-Befehl immer auf das laufende Profil. Sollen die Parameter eines anderen Profils ausgelesen werden, muss der Befehl um die Angabe des Namens des Profils ergänzt werden.
Beispiel für das Auslesen der Benutzer von Profil "Profile_2":
GET /configuration/administration/users?profile=Profile_2
Als Antwort werden sämtliche Benutzer von Profil "Profile_2" im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile_2"
},
"config": {
"user": [
{
"active": "1",
"username": "insys",
"group": "readwrite",
"index": "user1"
},
{
"active": "1",
"username": "icom",
"group": "readwrite",
"index": "user2"
},
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3"
}
]
}
}
Filtern einer Liste im GET-Befehl
Bei Listen gibt ein GET-Befehl sämtliche Einträge zurück. Um nur die gewünschten Einträge in der Antwort zu sehen, kann der Befehl mit einem Filter übergeben werden. Für den Filter wird der Parameter, nach dem gefiltert werden soll, ein Operator für die Filterfunktion und der gewünschte Wert des Parameters in einem JSON-Array angegeben:
{
"p" : "parameter",
"o" : "operator",
"v" : "value"
}
Der Parameter ist einer der Konfigurationsparameter im Listeneintrag.
Der Operator ist entweder eq (der Parameter muss exakt den Wert haben) oder like (der Parameter muss den Wert enthalten ohne Rücksicht auf Groß-/Kleinschreibung).
Der Value ist der Wert, dem der Parameterwert entsprechen oder der darin enthalten sein muss.
Beispiel für das Ausgeben aller Benutzer mit der Berechtigung "Lesen":
GET /configuration/administration/users?filter={"p":"group","o":"eq","v":"read"}
Als Antwort werden die Parameter sämtlicher Benutzer mit der Berechtigung "Lesen" im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
},
"config": {
"user": [
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3"
}
]
}
}
Es sind auch mehrfache Filter möglich. Dann werden sämtliche Filter mit einem logischen UND kombiniert, d.h. alle Filterkriterien müssen erfüllt werden, damit ein Eintrag angezeigt wird.
Beispiel für das Ausgeben aller Benutzer mit der Berechtigung "Lesen" und dem String "ic" im Benutzernamen:
GET /configuration/administration/users?filter=[{"p":"group","o":"eq","v":"read"},{"p":"username","o":"like","v":"ic"}]
Abfrage der Anzahl der Listeneinträge mit dem GET-Befehl
Um die Anzahl der Einträge einer Liste abzufragen, wird der Befehl um den Parameter return_size ergänzt, wobei mit dem Parameter ein Wert übergeben muss, der allerdings irrelvant ist.
Beispiel für das Ausgeben der Anzahl der angelegten Benutzer:
GET /configuration/administration/users?return_size=1
Als Antwort wird die Anzahl der Benutzer im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
},
"config": {
"list_size": 3
}
}
Wird dabei ein Filter mit übergeben, wird nur die Anzahl der Listeneinträge ausgegeben, welche den Filterkriterien entsprechen.
Beispiel für das Ausgeben der Anzahl der angelegten Benutzer mit der Berechtigung "Lesen" und dem String "ic" im Benutzernamen:
GET /configuration/administration/users?filter=[{"p":"group","o":"eq","v":"read"},{"p":"username","o":"like","v":"st"}]&return_size=1
Hinzufügen von Parametern (POST)
Mit der HTTP-Methode POST werden Einträge zu Listen hinzugefügt. Dabei darf der Eintrag keinen Listenindex haben, da der Eintrag am Ende der Liste hinzugefügt wird.
Beispiel für das Hinzufügen des neuen Benutzers "newuser" mit Leserechten zum Profil "Profile" und gleichzeitiger Aktivierung des geänderten Profils:
POST /configuration/administration/users
{
"profile": {
"name": "Profile",
"activate": "1"
},
"config": {
"user": [
{
"active": "1",
"username": "newuser",
"group": "read"
}
]
}
}
Obiges Beispiel fügt den neuen Benutzer dem Profil "Profile" hinzu. Der Parameter "name": "Profile" spezifiziert das Profil, auf das die Änderungen Anwendung finden. Wird er weggelassen, wird der Benutzer dem laufenden Profil hinzugefügt. Der Parameter "activate": "1" aktiviert das geänderte Profil. Wird er weggelassen, wird das Profil lediglich geändert, aber nicht aktiviert. Sollen Änderungen auf das laufende Profil Anwendung finden und soll keine Aktivierung stattfinden, kann der gesamte Profil-Abschnitt weggelassen werden.
Manche Funktionen des Routers erfordern Listen innerhalb von Listen.
Beispiel für das Hinzufügen eines neuen Interfaces "net3" mit einem Verbindungs-Check-Intervall von 13 Minuten und der Fallback-WAN-Kette "wan2" zur WAN-Kette "wan1":
POST /configuration/wan/wans
{
"config": {
"wan_chain": [
{
"name": "wan1",
"interface": [
{
"interface": "net3",
"check_interval": "13",
"check_fail_wan": "wan2",
"check_type": "none"
}
]
}
]
}
}
Ändern von Parametern (PUT)
Mit der HTTP-Methode PUT werden bestehende Einträge in Listen geändert.
Beispiel für das Ändern des Benutzernamens des Benutzers "user2" auf "newuser" der Rechte auf Lesen/Schreiben:
PUT /configuration/administration/users
{
"profile": {
"name": "Profile"
},
"config": {
"user": [
{
"username": "newuser",
"group": "readwrite",
"index": "user2"
}
]
}
}
Der Listen-Identifikator, hier der Parameter "index" ist zwingend erforderlich zur Bestimmung des zu ändernden Eintrags.
Löschen von Parametern (DELETE)
Mit der HTTP-Methode DELETE werden komplette Listen oder bestehende Einträge aus Listen gelöscht. Werden keine Filter verwendet, werden alle Einträge löscht. Filter ermöglichen ein gezieltes Löschen bestimmter Einträge.
Beispiel für das Löschen aller Hostnamen:
DELETE /configuration/administration/hostnames
Beispiel für das Löschen aller Benutzer mit dem String "test" im Benutzernamen aus dem Profil "Profile_2":
DELETE /configuration/administration/users?filter={"p":"username","o":"like","v":"test"}&profile=Profile_2
Beispiel für das Löschen aller WAN-Interfaces:
DELETE /configuration/wan/wans?delete=interface
Beispiel für das Löschen des Interfaces "group2" aus den WAN-Ketten:
DELETE /configuration/wan/wans?delete=interface&filter={"p":"interface","o":"eq","v":"group2"}
Status-Abfragen
Zum Abfragen von Statusinformationen steht der Befehl (HTTP-Methode) GET zur Verfügung. Für Abfragen von Statusinformationen beginnt der Pfad immer mit /status/.
Beispiel für das Auslesen der aktuellen Werte der Geräteinfo:
GET /status/device_info
Als Antwort werden sämtliche Parameter mit ihren Werten im JSON-Format zurückgegeben:
{
"status": {
"slot": [
{
"board_type": "M3CPU",
"hardware_features": "0x00",
"hardware_version": "3",
"firmware_version": "4.3",
"serial_number": "12345678"
},
{
"board_type": "M3PWL",
"hardware_features": "0x04",
"hardware_version": "2",
"firmware_version": "",
"serial_number": ""
},
]
}
}
Anzeigen von Log-Dateien und Profilen
Zum Anzeigen von Log-Dateien und Profilen steht der Befehl (HTTP-Methode) GET zur Verfügung. Für die Anzeige von Log-Dateien und Profilen beginnt der Pfad immer mit /download/.
Log-Dateien
Eine Übersicht aller im Router gespeicherten Log-Dateien erhält man durch einen GET-Aufruf der Log-Datei-Liste:
GET /download/log?list_files=1
{
"log_files": [
"configd/current",
"configd/log-2018-02-20-09:45:39.bz2",
"httpd/current",
"httpd/log-2018-02-20-09:45:39.bz2",
...
]
}
Die Anzeige einer Log-Datei erhält man durch einen GET-Aufruf der jeweiligen Datei:
GET /download/log?log_file=configd/current
2018-04-19 07:44:46 [configd] Started
2018-04-19 07:44:50 [configd] reading m3 config again
2018-04-19 07:44:51 [configd] M3 config read
2018-04-19 08:25:11 [configd] Profile 'Profile' activated
2018-04-19 08:25:11 [configd] cleaning persistent database
Profile
Eine Übersicht aller im Router gespeicherten Profile erhält man durch einen GET-Aufruf der Profile-Liste:
GET /download/profiles?list_files=1
{
"profiles": [
"Profile",
"Profile_2"
]
}
Die Anzeige eines Profils erhält man durch einen GET-Aufruf des jeweiligen Profils:
GET /download/profiles?profile=Profile
Da das Profil ein Binär-Format aufweist, muss es entsprechend abgespeichert werden.
Debugging und Auslösen manueller Aktionen
Zum Debugging und Auslösen manueller Aktionen steht der Befehl (HTTP-Methode) POST zur Verfügung. Für das Debugging und Auslösen manueller Aktionen beginnt der Pfad immer mit /operation/.
Für Debugging-Zwecke ist es möglich, manuelle Aktionen auszuführen.
Beispiel für das manuelle Versenden der Nachricht "message1":
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "message",
"options" : {
"message" : "message1"
}
}
}
Beispiel für das manuelle Einschalten der Info-LED:
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "info_led",
"options" : {
"info_led" : "on"
}
}
}
Siehe dazu auch dieses Beispiel für die Vorgehensweise zum Ermitteln der Befehls-Syntax.
Beispiel für eine Abfrage der Konfiguration mit einem cURL-Befehl
Mit folgendem cURL-Befehl kann beispielsweise die Konfiguration der REST-Schnittstelle im Menü Administration ausgelesen werden:
curl -X GET -H "Content-type: application/json" -H "Accept: application/json" -u "insys:icom" "http://192.168.1.10:9090/configuration/administration/rest"
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "1",
"https_active": "1",
"http_port": "9090",
"https_port": "9091",
"https_cert": "app_cert",
"https_key": "app_key"
}
}
Zum Ermitteln der cURL-Syntax, siehe die Seite Befehlsreferenz und den dort verlinkten Configuration Guide.
Tipp: Bei Problemen mit der cURL-Syntax ist es hilfreich, die Option '-v' (verbose) zu verwenden, um die Fehlersuche zu vereinfachen:
curl -v -X GET -H "Content-type: application/json" -H "Accept: application/json" -u "insys:icom" "http://192.168.1.10:9090/configuration/administration/rest"