Data import/export interface

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 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 editor.swagger.io) verwendet werden um automatisch Clients für die REST Schnittstelle zu generieren.

SwaggerUI

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 mit gesendet 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.

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.

ApiKey generieren

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.