Übersicht
IDIAL stellt eine REST API bereit, über die sich der Bestand der angebundenen OPC UA Endpoints und ihrer Zertifikate verwalten lässt. Zusätzlich ermöglicht die API die Konfiguration von PKI- und EST-Integrationen, die Überwachung des Zertifikatslebenszyklus sowie die Steuerung der TLS-Einstellungen des IDIAL-Containers selbst. Die API wird durch APIFlask (Python) bereitgestellt und veröffentlicht automatisch eine OpenAPI-Spezifikation unter /openapi.json sowie eine interaktive Dokumentation unter /docs.
Basis-URL
Die Standard-Basis-URL der IDIAL REST API lautet:
http://127.0.0.1:5000
Der Host kann beim Start des Containers überschrieben werden. TLS lässt sich über POST /tls aktivieren. Sobald TLS aktiv ist, gilt folgendes Schema:
https://<host>:5000
Authentifizierung
Die meisten Endpoints erfordern einen API-Schlüssel, der als HTTP-Header übergeben wird:
X-API-Key: <your-api-key>
Der API-Schlüssel wird über die Datei secrets/idial_api_key.txt innerhalb des IDIAL-Containers konfiguriert. Alternativ kann die Umgebungsvariable IDIAL_API_KEY_FILE verwendet werden, um einen abweichenden Dateipfad anzugeben.
Endpoints ohne Authentifizierung
Die folgenden Endpoints sind ohne API-Schlüssel erreichbar:
GET /systeminfoGET /tls
Content-Type
Alle Anfragen und Antworten verwenden Content-Type: application/json.
Fehlerformat
Tritt ein Fehler auf, gibt die API eine JSON-Antwort im folgenden Format zurück:
{
"error": "string"
}
Endpoint-Übersicht
Die folgende Tabelle listet alle 35 Endpoints der IDIAL REST API, gruppiert nach Kategorie.
Die OpenAPI-Spezifikation ist unter /openapi.json abrufbar. Eine interaktive Swagger UI steht unter /docs zur Verfügung, solange IDIAL läuft.
| Kategorie | Methode | Pfad | Auth |
|---|---|---|---|
| System | GET | /systeminfo | Nein |
| System | POST | /systeminfo | Ja |
| System | GET | /gds/systeminfo | Ja |
| System | GET | /crl/systeminfo | Ja |
| System | GET | /supported-devices | Ja |
| TLS-Konfiguration | GET | /tls | Nein |
| TLS-Konfiguration | POST | /tls | Ja |
| Inventory | GET | /inventory | Ja |
| Inventory | POST | /inventory | Ja |
| Inventory | PATCH | /inventory | Ja |
| Inventory | GET | /gds/inventory | Ja |
| Inventory | POST | /gds/inventory | Ja |
| Inventory | PATCH | /gds/inventory | Ja |
| Inventory | GET | /gds/inventory/{host_or_url} | Ja |
| Inventory | GET | /ssh/inventory | Ja |
| Zertifikatsüberwachung | POST | /gds/monitor/crt | Ja |
| Zertifikatsüberwachung | GET | /gds/monitor/crt/{host_or_url} | Ja |
| Zertifikatsüberwachung | POST | /gds/inventory/crt | Ja |
| Zertifikatsüberwachung | GET | /gds/inventory/crt/{host_or_url} | Ja |
| Zertifikatsüberwachung | GET | /gds/monitor/plc/{host_or_url} | Ja |
| Trust List | POST | /gds/monitor/trustlist | Ja |
| Trust List | GET | /gds/monitor/trustlist/{host_or_url} | Ja |
| Trust List | DELETE | /gds/monitor/trustlist | Ja |
| GDS Push | POST | /gds/push | Ja |
| GDS Push | GET | /gds/push/{host_or_url} | Ja |
| GDS Push | POST | /gds/push/change | Ja |
| GDS Firmware | POST | /gds/firmware | Ja |
| GDS Firmware | GET | /gds/firmware/{host_or_url} | Ja |
| GDS Status | GET | /gds/status/{host_or_url} | Ja |
| GDS Client-Zertifikat | GET | /gds/crt | Ja |
| PKI | GET | /pki | Ja |
| PKI | GET | /pki/ca | Ja |
| PKI | GET | /pki/crl | Ja |
| PKI | POST | /pki/sign-client-csr | Ja |
| PKI | POST | /pki/sign-server-csr | Ja |