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

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.