Data import/export interface
Weitere Optionen
The data import/export interface of HITGuard is a REST API that complies with the OpenAPI 3.0 specification. It is therefore an API that can be used by applications.
This page describes how to enable the REST API, how to get permission to use the REST API (ApiKeys) and where to find the REST API documentation (SwaggerUI).
Successfully performed imports also generate an import log in the menu item Data import ("Administration → Data import | Import logs)!
Configuration
To enable the REST API, the following property must be set in the configuration file "appsettings.json":
"RestApi": { "Enabled": true }
If this property does not exist or it is set to "false", the REST API is completely disabled and Administrators will no longer see the ApiKey section under their profile nor the REST API settings under Global Settings.
Settings
If the REST API has been enabled in "appsettings.json", Administrators will find a new area in the Global Settings, where the REST API can be enabled and disabled at any time.
- Activate REST API:
- This option enables the endpoints of the REST API. If this option is disabled, the REST API does not accept any requests.
- Activate SwaggerUI:
- This option enables the SwaggerUI, which is an interactive documentation of the REST API. It can be accessed at "/swagger".
- This option has no effect on the functionality of the REST API. If it is disabled, the REST API will still work if it is enabled.
- This page is only relevant for developers who want to communicate with the REST API.
- If the documentation is no longer needed, the SwaggerUI page should be disabled.
Swagger/OpenAPI documentation
As described before, the documentation of the REST API can be found under "/swagger" when the SwaggerUI is enabled.
On this page, developers will find all the information they need to communicate with the REST API.
On this page, you also find the JSON description of the REST API. This description can be used by tools (e.g. editor.swagger.io) to automatically generate clients for the REST API.
Important: ID parameters mentioned in the documentation do not refer to HITGuard internal IDs in the context of the REST API. They refer to the HITGuard field "External ID".
| Overview | |
|---|---|
| Structural analysis edges | PUT/api/v2/asset-edges → Adds relationships in the structural analysis between resources, organizational units, processes, and data categories. |
| Tickets | PUT/api/tickets → Creates a new ticket in a management system or updates it. DELETE/api/tickets/{id} → Deletes a ticket by its external ID. |
| Management systems | GET/api/management-systems → Produces a list of the available management systems. This list contains the management system IDs. |
| Users | DELETE/api/users/deactivate/{userName} → Deactivates or deactivates and anonymizes a user by the username. |
| Data categories | PUT/api/data-categories → Creates new data categories or updates them. GET/api/data-categories → Produces a list of the available data categories. GET/api/data-categories/data-classes → Produces a list of the available data classes. DELETE/api/data-categories/{id} → Deletes a data category by the external key. |
| Measures | PUT/api/v2/measures → Creates a new measure or updates it. PUT/api/measures/close/{id} → Puts a measure into the state "Completed" by the ID. PUT/api/measures/close/byKey/{id} → Puts a measure into the state "Completed" by the external ID. DELETE/api/measures/{id} → Löscht eine Maßnahme anhand der ID. GET/api/measures/{state} → Produces a list of all measures in a specific state. |
| Organizational units | PUT/api/org-units → Creates an organizational unit or updates it. GET/api/org-units → Produces a list of organizational units. DELETE/api/org-units/{id} → Deletes an organizational unit by the ID. |
| Processes | PUT/api/processes → Creates a process or updates it. GET/api/processes → Produces a list of processes. DELETE/api/processes/{id} → Deletes a process by the ID. |
| Resources | PUT/api/resources → Creates a resource or updates it. GET/api/v2/resources → Produces a list of resources. GET/api/v2/resources/{id} → Retrieves the information of a specific resource by the ID. DELETE/api/resources/{id} → Deletes a resource by the ID. |
| Risks | PUT/api/risks → Creates a risk in a management system or updates it. GET/api/v2/risks/ → Produces a list of all available risks. GET/api/v2/risks/{id} → Retrieves the information of a specific risk by the ID. DELETE/api/risks/{id} → Deletes a risk by the ID. |
| Suppliers | PUT/api/suppliers → Creates or updates a supplier. |
Versionierung
Aktuell gibt es 2 Versionen der API: "v1" und "v2". In Swagger kann zwischen den Versionen hin und her gewechselt werden.
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
- PUT /api/v2/measures ersetzt PUT /api/measures
- Kanten der Strukturanalyse (AssetEdges)
- PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
- Die Parameter "sourceType" und "targetType" verwenden jetzt Enumerationswerte
- PUT /api/v2/asset-edges ersetzt PUT /api/asset-edges
- Ressourcen (Resources)
- alle Endpunkte wurden in "v1" als veraltet markiert
- Der Parameter "modelSegment" verwendet jetzt Enumerationswerte
- alle Endpunkte wurden in "v1" als veraltet markiert
- 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.
- GET /api/v2/risks ersetzt GET /api/risks/{managementSystemId}
Alle anderen Endpunkte werden zurzeit nur über "v1" angeboten. Bevor "v1" wirklich entfernt wird, werden alle Endpunkte in "v2" angeboten.
ApiKeys
All endpoints of the REST API are secured via ApiKeys!
In order for requests to the REST API to be accepted, a valid ApiKey must be sent in the authorization header of each request.
ApiKeys can only be created by Administrators on their profile (click on the profile picture). Each Administrator can have only one valid ApiKey at any time.
ApiKeys can be created with an expiration date. When the ApiKey expires, no more requests can be made with it.
The ApiKey is shown only once! If you do not copy it at that moment, you need to create a new ApiKey. By clicking on the button to the left of the ApiKey, the ApiKey will be copied to your clipboard. Make sure that you save the ApiKey in a safe location.
An Administrator can revoke their own ApiKey at any time, which means that no more requests can be made via that ApiKey afterwards.
To manage ApiKeys, it is recommended to create an Administrator for each application that controls the REST API and thus to obtain an ApiKey for each application. This way, access can be taken away from an application at any time.