Ü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, die Lizenzverwaltung, die Planung von Wartungsfenstern 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>
Alternativ wird das Bearer-Token-Format akzeptiert:
Authorization: Bearer <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 /docsGET /openapi.jsonGET /pki/ca/{pki_id}GET /pki/crl/{pki_id}
Content-Type
Alle Anfragen und Antworten verwenden Content-Type: application/json, mit Ausnahme von Zertifikat- und CRL-Download-Endpoints, die Binärdaten zurückgeben.
Fehlerformat
Tritt ein Fehler auf, gibt die API eine JSON-Antwort im folgenden Format zurück:
{
"error": "string"
}
Interaktive Dokumentation
Die OpenAPI-Spezifikation ist unter /openapi.json abrufbar. Eine interaktive Swagger UI steht unter /docs zur Verfügung, solange IDIAL läuft. Die Aliases /swagger, /swagger-ui und /api/docs leiten ebenfalls auf /docs weiter.
Endpoint-Übersicht
Die folgende Tabelle listet alle 74 Endpoints der IDIAL REST API, gruppiert nach Kategorie.
| 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 |
| System | GET | / | Ja |
| System | GET | /opcua_gds_dashboard.html | Nein |
| TLS-Konfiguration | GET | /tls | Ja |
| TLS-Konfiguration | POST | /tls | Ja |
| Lizenz | POST | /systeminfo/lic | Ja |
| Lizenz | GET | /systeminfo/lic | Ja |
| Lizenz | DELETE | /systeminfo/lic | Ja |
| Inventar | GET | /inventory | Ja |
| Inventar | POST | /inventory | Ja |
| Inventar | PATCH | /inventory | Ja |
| Inventar | GET | /gds/inventory | Ja |
| Inventar | POST | /gds/inventory | Ja |
| Inventar | PATCH | /gds/inventory | Ja |
| Inventar | GET | /gds/inventory/{host_or_url} | Ja |
| Inventar | DELETE | /gds/inventory/{host_or_url} | Ja |
| Inventar | POST | /gds/inventory/user | Ja |
| Inventar | PATCH | /gds/inventory/user | Ja |
| Inventar | GET | /gds/inventory/trustlist | Ja |
| Inventar | 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 |
| Zertifikatsüberwachung | GET | /gds/monitor/firmware/{host_or_url} | Ja |
| Zertifikatsüberwachung | GET | /gds/monitor/status/{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 |
| Trust List | DELETE | /gds/monitor/trustlist/{host_or_url} | Ja |
| GDS Push | POST | /gds/push | Ja |
| GDS Push | GET | /gds/push/{host_or_url} | Ja |
| GDS Push | POST | /gds/push/onboarding | Ja |
| GDS Push | GET | /gds/push/onboarding/{host_or_url} | Ja |
| GDS Push | POST | /gds/push/change | Ja |
| GDS Firmware | POST | /gds/firmware | Ja |
| GDS Firmware | GET | /gds/monitor/firmware/{host_or_url} | Ja |
| GDS Client-Zertifikat | GET | /gds/crt | Ja |
| PKI | GET | /pki | Ja |
| PKI | GET | /pki/inventory | Ja |
| PKI | GET | /pki/inventory/{pki_id} | Ja |
| PKI | GET | /pki/inventory/creator/{creator_id} | Ja |
| PKI | POST | /pki/inventory | Ja |
| PKI | PATCH | /pki/inventory/{pki_id} | Ja |
| PKI | DELETE | /pki/inventory/{pki_id} | Ja |
| PKI | GET | /pki/exec/validate/{pki_id} | Ja |
| PKI | GET | /pki/exec/validate-strict/{pki_id} | Ja |
| PKI | GET | /pki/ca/{pki_id} | Nein |
| PKI | GET | /pki/crl/{pki_id} | Nein |
| PKI | GET | /pki/crt/{pki_id} | Ja |
| PKI | POST | /pki/sign-client-csr | Ja |
| PKI | POST | /pki/sign-server-csr | Ja |
| Wartung | GET | /maintenance/inventory | Ja |
| Wartung | GET | /maintenance/inventory/{window_id} | Ja |
| Wartung | POST | /maintenance/inventory | Ja |
| Wartung | PATCH | /maintenance/inventory/{window_id} | Ja |
| Wartung | DELETE | /maintenance/inventory/{window_id} | Ja |
| Wartung | GET | /maintenance/rule | Ja |
| Wartung | POST | /maintenance/rule | Ja |
| Wartung | PATCH | /maintenance/rule/{rule_id} | Ja |
| Wartung | DELETE | /maintenance/rule/{rule_id} | Ja |
| Wartung | POST | /maintenance/test/{window_id} | Ja |
| Datenbank | POST | /create/dummy-db | Ja |
| Datenbank | DELETE | /sql/{totp_code} | Ja |
Lizenz & Feature-Gating
Die meisten Endpoints erfordern das Lizenz-Feature core. Jede Anfrage wird gegen die installierte Lizenz geprüft. Ist keine gültige Lizenz installiert, gibt die API 403 zurück.
Der Endpoint /systeminfo/lic ist vom Feature-Gating ausgenommen und erfordert ausschließlich den API-Schlüssel.