Datenimport/-export Schnittstelle/en

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.

SwaggerUI

Overview
Structural analysis edges	PUT/api/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/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/resources → Produces a list of resources. GET/api/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/risks/{managementSystemId} → Produces a list of all available risks of a management system. GET/api/risks/byKey/{riskExternalId} → Retrieves the information of a specific risk by the ID. DELETE/api/risks/{id} → Deletes a risk by the ID.

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.

Section to manage ApiKey

ApiKeys can be created with an expiration date. When the ApiKey expires, no more requests can be made with it.

Generate ApiKey

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.

Copy ApiKey

An Administrator can revoke their own ApiKey at any time, which means that no more requests can be made via that ApiKey afterwards.

Revoke ApiKey

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.