REST API – Einstieg und Automatisierung

Mit der eEKAS REST API können Sie Statusinformationen abrufen und wiederkehrende Verwaltungsaufgaben automatisieren. Dieser Einstieg zeigt die Einrichtung und eine erste Abfrage. Die vollständige API-Referenz beschreibt die einzelnen Operationen.

Verwendung und Support: Die Nutzung der API erfolgt in eigener Verantwortung. API-Nutzung ist nicht durch den Support abgedeckt.

API-Zugriff einrichten

Öffnen Sie die Systemeinstellungen der eEKAS-Webverwaltung und den Bereich REST API. Aktivieren Sie die API.
Wählen Sie das Verwaltungsnetz, HTTPS und den API-Port. Standard ist 18443. Im Cluster verwendet jeder Knoten seine eigene Adresse im ausgewählten Netz. Beschränken Sie den Netzwerkzugriff auf die benötigten Verwaltungsclients.
Konfigurieren Sie einen API-Benutzer und API-Schlüssel. Für einen neuen Schlüssel können Sie das Schlüsselfeld leer lassen und einen sicheren Schlüssel erzeugen lassen; ein vorhandener Schlüssel kann beibehalten werden. Bewahren Sie den Schlüssel in einem geschützten Secret Store auf.
Wählen Sie die kleinste benötigte Rolle. Für reine Statusabfragen eignet sich read-only; für S3-Verwaltung ist s3-admin vorgesehen. Verfügbarkeit von Operationen und Rollenberechtigung müssen zusammen geprüft werden.
Legen Sie bei Bedarf ein Ablaufdatum fest. Prüfen Sie Anfragelimit und Aufbewahrungszeit für Idempotenzantworten.
Aktivieren Sie OpenAPI und Swagger UI, wenn Sie die installationsbezogene Referenz benötigen. Auch diese Dokumentation erfordert einen gültigen API-Schlüssel.
Speichern Sie die API-Einstellungen. Wenn Sie die Clusteroption wählen, werden Konfiguration und Neustart der API auf alle Clusterknoten angewendet. Prüfen Sie anschließend die Erreichbarkeit der benötigten Knoten.

Verwenden Sie einen DNS-Namen, der zum HTTPS-Zertifikat passt. Bei einer privaten Zertifizierungsstelle geben Sie dem Client die CA-Datei. Lassen Sie die Zertifikatsprüfung aktiviert. CORS wird nur für Browseranwendungen mit Zugriff von einer anderen Herkunft benötigt; für curl oder serverseitige Skripte ist es nicht erforderlich.

Erste Statusabfrage

Ersetzen Sie Hostname und Schlüssel durch Ihre Werte. Das Beispiel liest den S3-Status und verändert keine Konfiguration. Führen Sie es auf Ihrem Verwaltungsclient aus; Administratorrechte auf dem Client sind dafür nicht erforderlich.

curl --silent --show-error --fail-with-body --include \
  --header 'X-API-Key: <API_KEY>' \
  'https://eekas.example.com:18443/api/v1/s3/status'

Bei einer privaten CA ergänzen Sie --cacert /pfad/ca.pem. Halten Sie echte Schlüssel aus gemeinsam genutzten Skripten, Versionsverwaltung, Terminalverlauf und Protokollen fern. Produktive Automatisierungen sollten den Schlüssel über einen geschützten Secret Store oder eine nur für den ausführenden Benutzer lesbare Clientkonfiguration laden.

Bewahren Sie den zurückgegebenen Header X-Correlation-ID für die Zuordnung einer Anfrage zu Diagnoseinformationen auf. Ein API-Schlüssel wird als Header X-API-Key gesendet; S3 Access Key und Secret Key sind andere Zugangsdaten für das S3-Protokoll.

Änderungen zuverlässig ausführen

Prüfen Sie Methode, Pflichtfelder, Rolle und Voraussetzungen in der Referenz Ihrer installierten Version. Testen Sie schreibende Aufrufe zunächst mit Testressourcen.
Passwörter, Secret Keys, Token und andere geheime Parameter gehören in einen JSON-Anfragekörper mit Content-Type: application/json. Geheime Werte in URLs werden abgewiesen.
Verwenden Sie für wiederholbare Änderungen einen eindeutigen Idempotency-Key pro logischem Vorgang. Wiederholen Sie denselben Vorgang mit demselben Schlüssel und identischer Anfrage; verwenden Sie für einen neuen Vorgang einen neuen Schlüssel. Die Aufbewahrungszeit ist begrenzt. Cluster-Mitgliedschaftsänderungen benötigen diesen Header.
HTTP 202 bestätigt die Annahme einer Hintergrundoperation, nicht deren erfolgreichen Abschluss. Speichern Sie die zurückgegebene Jobkennung und fragen Sie GET /api/v1/jobs?job_id=<JOB_ID> ab, bis der Job abgeschlossen ist. Prüfen Sie Ergebnis und tatsächlichen Ressourcenstatus.
Nach einem Verbindungsabbruch prüfen Sie zuerst Job- oder Ressourcenstatus. Wiederholen Sie eine Änderung nicht blind.

Antworten und Fehler behandeln

HTTP-Status	Vorgehen
200 / 201	Antwort und Ergebnis prüfen; 201 steht üblicherweise für eine erstellte Ressource.
202	Hintergrundjob bis zum Abschluss verfolgen.
400 / 422	Parameter, JSON-Inhalt und Voraussetzungen korrigieren.
401 / 403	API-Schlüssel, Ablaufdatum und Rollenberechtigung prüfen.
404 / 405	Pfad, Ressource, HTTP-Methode und aktivierte Dokumentation prüfen.
409	Konflikt mit dem aktuellen Systemzustand prüfen.
428	Erforderlichen Idempotency-Key ergänzen.
429 / 503	Anfragerate reduzieren; Retry-After berücksichtigen, sofern vorhanden. Kontrollierte Wiederholungen mit Wartezeit verwenden.
500	Fehlermeldung und Korrelationskennung erfassen; vor Wiederholung den Zustand prüfen.

Fehlerantworten enthalten ein JSON-Feld error. Protokollieren Sie Status, Operation, Zeit und Korrelationskennung, ohne geheime Header oder Anfragekörper zu speichern.

S3-Replikation und Sicherung automatisieren

Für lesende Abfragen bietet die Referenz GET /api/v1/object-storage/replication und GET /api/v1/object-storage/replication/backups. Schreibende Aktionen, Einladungen, Wiederherstellung und Bestätigungsfelder sind in der API-Referenz und dem ergänzenden S3-Ablaufleitfaden beschrieben.

Die betrieblichen Voraussetzungen gelten auch bei API-Aufrufen: leeres Replikationsziel, Zertifikatsvertrauen, Isolation des alten Primärstandorts, geprüfte Wiederherstellungspunkte und WORM-Schutz. Lesen Sie dazu S3-Replikation und Wiederherstellung sowie SMB-Freigaben mit S3-WORM.

Referenz und Versionsstand

Unter eEKAS REST API-Referenz finden Sie die vollständige Referenz mit 285 Operationen, Stand 8. Oktober 2026. Für Ihre Installation ist die dort bereitgestellte OpenAPI-Spezifikation maßgeblich. Prüfen Sie Ihre Automatisierungen nach einem eEKAS-Update erneut.