Übersetzungen exportieren

Einstellungen

Gruppe

Sprache

Format

Für die Offline-Übersetzung exportieren

Im systemeigenen Format exportieren

Im CSV-Format exportieren

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 ([[Special:MyLanguage/Datenimport|"Administration → Datenimport | Importprotokolle]])!

[[Datei:REST API Importprotokoll.png|thumb|left|900px]]

== Konfiguration ==

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

* <code>"RestApi": { "Enabled": true } </code>

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.

[[Datei:REST API Einstellungen.png|thumb|left|902px]]

* 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. [https://editor.swagger.io editor.swagger.io]) verwendet werden, um automatisch Clients für die REST Schnittstelle zu generieren.

'''Wichtig''': ID Parameter, die in der Dokumentation erwähnt werden, beziehen sich im Kontext der REST API nicht auf HITGuard interne IDs, sondern auf die in HITGuard hinterlegte "ID in Drittsystem".

[[Datei:REST API Swagger.png|thumb|left|900px|SwaggerUI]]

{| class="wikitable"
! colspan="2" | Überblick
|-
!Kanten der Strukturanalyse
|PUT /api/v2/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/v2/measures → Erstellt neue Maßnahmen bzw. aktualisiert diese. GET /api/measures → Erzeugt eine Liste aller vorhandenen Maßnahmen. 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/v2/resources → Erstellt eine Ressource bzw. aktualisiert diese. GET /api/v2/resources → Erstellt eine Liste der Ressourcen. GET /api/v2/resources/{id} → Holt die Information zu einer bestimmten Ressource anhand der ID. DELETE /api/v2/resources/{id} → Löscht eine Ressource anhand der ID.
|-
!Risiken
|PUT /api/risks → Erstellt ein Risiko in einem Managementsystem bzw. aktualisiert dieses. GET /api/v2/risks/ → Erzeugt eine Liste aller vorhandenen Risiken. GET /api/v2/risks/{id} → Holt die Information zu einem bestimmten Risiko anhand der externen ID. DELETE /api/risks/{id} → Löscht ein Risiko anhand der ID.
|-
!Lieferanten
|PUT /api/suppliers → Erstellt oder aktualisiert einen Lieferanten.
|-
|}

== Versionierung ==
Aktuell gibt es 2 Versionen der API: "v1" und "v2". In Swagger kann zwischen den Versionen hin und her gewechselt werden.
[[Datei:Swagger version wechseln.png|ohne|mini|Wechseln der Version im Swagger]]
Zur Zeit sind die Endpunkte auf diese beiden Versionen aufgeteilt und man sollte aktuell beide Versionen verwenden.

Endpunkte, die in "v1" als veraltet ("'''Deprecated"''') markiert sind, sollten nicht mehr verwendet und werden in Zukunft entfernt. Verwenden Sie stattdessen die Endpunkte in "v2" dafür.

=== Changelog ===

==== Änderungen "v1" auf "v2" ====

* Maßnahmen (Measures)
** PUT /api/v2/measures ersetzt PUT /api/measures
*** Einstellungen zur Wirksamkeitspüfung können nicht mehr gesetzt oder verändert werden, da dies auf interne IDs angewiesen ist
*** Der "ID" Parameter verweist jetzt auf die in HITGuard hinterlegte "ID in Drittsystem" und nicht mehr die interne ID
** PUT /api/measures/close/{id}
*** wurde als veraltet markiert, da dies eine interne ID verwendet hat → nur noch  PUT /api/measures/close/byKey verwenden!
** Generell
*** Der Parameter "state" verwendet jetzt Enumerationswerte
* Kanten der Strukturanalyse (AssetEdges)
** PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
*** Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
* Ressourcen (Resources)
** alle Endpunkte wurden in "v1" als veraltet markiert
*** Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
* Risiken (Risks)
** GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
*** Der Pfad-Parameter "managementSystemId" wurde entfernt. Stattdessen können jetzt die optionalen Query-Parameter "managementSystemId" und "includePublicRisks" verwendet werden um Risiken abzufragen und zu filtern.
** GET /api/v2/risks/{id} ersetzt GET /api/risks/byKey/{id}
*** Endpunkt wurde angepasst um konsistent zu den anderen Endpunkten zu sein.

Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.

== 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.

[[Datei:REST API ApiKey Abschnitt.png|thumb|left|900px| Abschnitt zum Verwalten des ApiKeys]]

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

[[Datei:REST API ApiKey generieren.png|thumb|left|900px| ApiKey generieren]]

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.

[[Datei:REST API ApiKey kopieren.png|thumb|left|900px| ApiKey kopieren]]

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

[[Datei:REST API ApiKey widerrufen.png|thumb|left|900px| ApiKey Widerrufen]]

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.