Datenimport/-export Schnittstelle

Bei der Datenimport/-export Schnittstelle von HITGuard handelt es sich um eine REST Schnittstelle, die sich an die OpenAPI 3.0 Spezifikation hält. Es handelt sich dabei also um eine Schnittstelle, die von Applikationen angesprochen werden kann.

Diese Seite beschreibt, wie die REST Schnittstelle aktiviert werden kann, wie man die Berechtigung zum Verwenden der REST Schnittstelle bekommt (ApiKeys) und wo die Dokumentation der REST Schnittstelle zu finden ist (SwaggerUI).

Erfolgreich durchgeführte Imports erzeugen im Menüpunkt Datenimport auch ein Importprotokoll ("Administration → Datenimport | Importprotokolle)!

Konfiguration

Um die REST Schnittstelle zu aktivieren, muss in der Konfigurationsdatei "appsettings.production.json" folgendes Property gesetzt sein:

"RestApi": { "Enabled": true }

Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle vollkommen deaktiviert und Administratoren sehen weder den Abschnitt "ApiKey" unter ihrem Profil noch die Einstellungen der REST Schnittstelle unter den Globalen Einstellungen.

Einstellungen

Wurde die REST Schnittstelle im "appsettings.production.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen, über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.

REST Schnittstelle aktivieren:

Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Requests entgegen.

SwaggerUI aktivieren:

Diese Option aktiviert die SwaggerUI. Dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.

Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.

Diese Seite ist nur für Entwickler relevant, die mit der REST Schnittstelle kommunizieren möchten.

Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

Swagger/OpenAPI Dokumentation

Wie vorher beschrieben, findet man die Dokumentation der REST Schnittstelle unter "/swagger", wenn die SwaggerUI aktiviert ist.

Auf dieser Seite finden Entwickler alle Informationen, die sie benötigen, um die REST Schnittstelle anzusprechen.

Auf dieser Seite ist auch die JSON Beschreibung der REST Schnittstelle zu finden. Diese Beschreibung kann von Tools (z.B. editor.swagger.io) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.

Überblick
Kanten der Strukturanalyse	PUT/api/asset-edges → Fügt Beziehungen in der Strukturanalyse hinzu zwischen Ressourcen, Organisationseinheiten, Prozessen und Datenkategorien.
Meldungen	PUT/api/tickets → Erstellt neue Meldungen in einem Managementsystem bzw. aktualisiert diese. DELETE/api/tickets/{id} → Löscht Meldungen anhand der ID im Drittsystem.
Managementsysteme	GET/api/management-systems → Erzeugt eine Liste der vorhandenen Managementsysteme. Diese Liste enthält die IDs der Managementsysteme.
Benutzer	DELETE/api/users/deactivate/{userName} → Deaktiviert bzw. deaktiviert und anonymisiert einen Benutzer anhand des Usernamens.
Datenkategorien	PUT/api/data-categories → Erstellt neue Datenkategorien bzw. aktualisiert diese. GET/api/data-categories → Erzeugt eine Liste der vorhandenen Datenkategorien. GET/api/data-categories/data-classes → Erzeugt eine Liste der vorhandenen Datenklassen. DELETE/api/data-categories/{id} → Löscht eine Datenkategorie anhand der ID im Drittsystem.
Maßnahmen	PUT/api/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. PUT/api/measures/close/{id} → Versetzt eine Maßnahme anhand der ID in den Status "Erledigt". PUT/api/measures/close/byKey/{id} → Versetzt eine Maßnahme anhand der ID im Drittsystem in den Status "Erledigt". DELETE/api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET/api/measures/{state} → Erzeugt eine Liste aller Maßnahmen in einem bestimmten Status.
Organisationseinheiten	PUT/api/org-units → Erstellt eine Organisationseinheit bzw. aktualisiert diese. GET/api/org-units → Erzeugt eine Liste der Organisationseinheiten. DELETE/api/org-units/{id} → Löscht eine Organisationseinheit anhand der ID.
Prozesse	PUT/api/processes → Erstellt einen Prozess bzw. aktualisiert diesen. GET/api/processes → Erzeugt eine Liste der Prozesse. DELETE/api/processes/{id} → Löscht einen Prozess anhand der ID.
Ressourcen	PUT/api/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET/api/resources → Erstellt eine Liste der Ressourcen. GET/api/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE/api/resources/{id} → Löscht eine Ressource anhand der ID.
Risiken	PUT/api/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. GET/api/risks/{managementSystemId} → Erzeugt eine Liste aller vorhandenen Risiken eines Managementsystems. GET/api/risks/byKey/{riskExternalId} → Holt die Information zu einem bestimmten Risiko anhand der ID. DELETE/api/risks/{id} → Löscht ein Risiko anhand der ID.

ApiKeys

Alle Endpunkte der REST Schnittstelle sind über ApiKeys gesichert!

Damit Requests an die REST Schnittstelle erfolgreich durchgeführt werden können, muss in jedem Request ein gültiger ApiKey im Authorization Header mitgesendet werden.

ApiKeys können dabei nur von Administratoren unter ihrem Profil (klicken auf das Profilbild) erstellt werden. Jeder Administrator kann zu jedem Zeitpunkt nur einen gültigen ApiKey haben.

ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.

Der ApiKey wird nur ein einziges Mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch Klick auf den Button links neben dem ApiKey, wird der ApiKey in Ihre Zwischenablage kopiert. Stellen Sie sicher, dass sie den ApiKey an einem sicheren Ort ablegen.

Ein Administrator kann seinen eigenen ApiKey jederzeit widerrufen, wodurch über den ApiKey anschließend keine Requests mehr durchgeführt werden können.

Um ApiKeys zu verwalten empfiehlt es sich, pro Applikation, die die REST Schnittstelle ansteuert, einen Administrator anzulegen, um einen ApiKey pro Applikation zu bekommen. Dadurch kann einer Applikation jederzeit der Zugriff enthoben werden.