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

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 can 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 under 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

Der ApiKey wird nur ein einziges mal angezeigt! Wenn Sie ihn hier nicht kopieren, müssen Sie einen neuen ApiKey erzeugen. Durch klicken 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.

ApiKey kopieren

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

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 genommen werden.