 |
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
In diesem Configuration Guide ist der Umgang mit der REST-Schnittstelle ausführlich beschrieben.
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 Web-/REST-Interface heruntergeladen werden. 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.
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.
Außerdem kann für jeden Konfigurationsparemeter das Schema abgefragt werden.
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
Mit der aktuellen Version der Firmware ist der Zugriff auf die REST-Schnittstelle des Routers über HTTPS standardmäßig aktiviert. Bevor ein Zugriff auf die REST-Schnittstelle über HTTP möglich ist, muss dies im Menü Administration auf der Seite Web/-REST-Interface entsprechend konfiguriert werden. Dazu muss der Zugang über HTTP zusätzlich aktiviert werden. Die Standard-Ports (80 für HTTP und 443 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. Bei aktiver Firewall muss die entsprechende Ausnahmeregel für den HTTP-Zugang aktiviert sein. Werden die Standard-Ports geändert, müssen auch die Ausnahmeregeln entsprechend angepasst werden.
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 auf der Seite Benutzer verwaltet wird.
Mit dem daraufhin erhaltenen Access-Token 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 auf der Seite 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:
{
"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:
{
"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
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.1 und den HTTPS-Port ist zum Beispiel:
192.168.1.1:443/api/v2_0/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 des Web-/REST-Interface:
GET /api/v2_0/configuration/administration/webinterface
Als Antwort werden sämtliche Parameter mit ihrer Einstellung im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "0",
"https_active": "1",
"http_port": "80",
"https_port": "443",
"https_cert": "device_cert",
"https_key": "device_key",
"session_timeout": "15",
"default_log_reverse": "1",
"default_language": "de",
"default_refresh_interval": "0",
"default_log_lines": "40",
"active_https": "1",
"active_clientauth": "0",
"https_clientauth_ca": "---",
"https_clientauth_crl": "---",
"https_clientauth_group": "readwrite",
"https_ca": "device_ca",
"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 /api/v2_0/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"
"last_activated": true,
"modified": true
},
"config": {
"unique": {
"password_hashes": "0"
},
"list": [
{
"active": "1",
"username": "insys",
"group": "readwrite",
"index": "user1",
"list_uid": "3e71d7bcbb"
},
{
"active": "1",
"username": "icom",
"group": "readwrite",
"index": "user2",
"list_uid": "bd998ab74a"
},
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3",
"list_uid": "878256c625"
}
]
}
}
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.
Werden mehrere Werte - getrennt durch ein Komma - angegeben, werden die Filter nach dem Prinzip einer ODER-Verknüpfung angewendet (Beispiel: "v" : ["value1","value2"]).
Beispiel für das Ausgeben aller Benutzer mit der Berechtigung "Lesen":
GET /api/v2_0/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"
"last_activated": true,
"modified": true
},
"list": [
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3",
"list_uid": "878256c625"
}
]
}
}
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 /api/v2_0/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 irrelevant ist.
Beispiel für das Ausgeben der Anzahl der angelegten Benutzer:
GET /api/v2_0/configuration/administration/users?return_size=1
Als Antwort wird die Anzahl der Benutzer im JSON-Format zurückgegeben:
{
"profile": {
"name": "Profile"
"last_activated": true,
"modified": true
},
"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 /api/v2_0/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 /api/v2_0/configuration/administration/users
{
"profile": {
"name": "Profile",
"activate": "1"
},
"config": {
"list": [
{
{
"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 /api/v2_0/configuration/wan/wans
{
"config": {
"list": [
{
"sublist": [
{
"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.
Beim Ändern bestehender Einträger wird der Eintrag über die Listen-ID (list_uid) bzw. Sublisten-ID (sublist_uid) identifiziert. Dazu muss zuvor mit einem GET-Request die bestehende Konfiguration abgefragt werden, um die ID zu ermitteln.
Beispiel für das Ändern des Benutzernamens des Benutzers mit der Listen-ID "878256c625" auf "newuser" und der Rechte auf Lesen/Schreiben:
PUT /api/v2_0/configuration/administration/users
{
"profile": {
"name": "Profile"
},
"config": {
"list": [
{
"username": "newuser",
"group": "readwrite",
"list_uid": "878256c625"
}
]
}
}
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 /api/v2_0/configuration/administration/hostnames
Beispiel für das Löschen aller Benutzer mit dem String "test" im Benutzernamen aus dem Profil "Profile_2":
DELETE /api/v2_0/configuration/administration/users?filter={"p":"username","o":"like","v":"test"}&profile=Profile_2
Beispiel für das Löschen aller WAN-Interfaces:
DELETE /api/v2_0/configuration/wan/wans?delete=interface
Beispiel für das Löschen des Interfaces "group2" aus den WAN-Ketten:
DELETE /api/v2_0/configuration/wan/wans?delete=interface&filter={"p":"interface","o":"eq","v":"group2"}
Schema-Abfragen
Zum Abfragen eines Konfigurationsschemas inklusive aller möglichen Werte steht der Befehl (HTTP-Methode) GET mit der Option "?append_scheme=1" zur Verfügung. Dabei werden sämtliche für eine Ressource möglichen und erlaubten Felder und Optionen ausgegeben
Beispiel für die Ausgabe des Schemas für die Konfiguration des E-Mail-Kontos:
GET /api/v2_0/configuration/events/email_account?append_scheme=1
Als Antwort werden sämtliche Konfigurationsoptionen im JSON-Format zurückgegeben:
{
{
"profile": {
"name": "Profile",
"last_activated": true,
"modified": false
},
"config": {
"unique": {
"address": "",
"real_name": "",
"server": "",
"encryption": "starttls",
"verify_peer": "",
"verify_host": "",
"port": "25",
"username": "",
"password": ""
}
},
"scheme": {
"parameters": {
"unique": [
{
"name": "address",
"type": "email_addr"
},
{
"name": "real_name",
"type": "string",
"max_len": 100
},
{
"name": "server",
"type": "peer",
"max_len": 100
},
{
"name": "encryption",
"type": "radio",
"items": [
{
"value": "none",
"translate": true,
"label": "none"
},
{
"value": "ssl",
"translate": true,
"label": "ssl"
},
{
"value": "starttls",
"translate": true,
"label": "starttls"
}
]
},
{
"name": "verify_peer",
"type": "checkbox"
},
{
"name": "verify_host",
"type": "checkbox"
},
{
"name": "port",
"type": "int",
"min": 1,
"max": 65535,
"steps": 1
},
{
"name": "username",
"type": "string",
"max_len": 100
},
{
"name": "password",
"type": "passwd",
"max_len": 100
}
]
}
}
}
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 /api/v2_0/status/device_info
Als Antwort werden sämtliche Parameter mit ihren Werten im JSON-Format zurückgegeben:
{
"status": {
"list": [
{
"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 /api/v2_0/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 /api/v2_0/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 /api/v2_0/profiles
{
"profiles": [
"name": "Profile",
"last_activated": false,
"modified": false
},
{
"name": "quick_start_profile",
"last_activated": true,
"modified": false
}
]
}
Die Anzeige eines Profils erhält man durch einen GET-Aufruf des jeweiligen Profils:
GET /api/v2_0/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 /api/v2_0/operation
{
"method" : "manual_action",
"params" : {
"type" : "message",
"options" : {
"message" : "message1"
}
}
}
Beispiel für das manuelle Einschalten der Info-LED:
POST /api/v2_0/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 des Web-/REST-Interface 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:443/api/v2_0/configuration/administration/webinterface"
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "0",
"https_active": "1",
"http_port": "80",
"https_port": "443",
"https_cert": "device_cert",
"https_key": "device_key",
"session_timeout": "15",
"default_log_reverse": "1",
"default_language": "de",
"default_refresh_interval": "0",
"default_log_lines": "40",
"active_https": "1",
"active_clientauth": "0",
"https_clientauth_ca": "---",
"https_clientauth_crl": "---",
"https_clientauth_group": "readwrite",
"https_ca": "device_ca",
"log_requests": "0"
}
}
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:/api/v2_0/configuration/administration/rest"