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 }

Existiert dieses Property nicht oder es ist auf "false" gesetzt, ist die REST Schnittstelle komplett deaktiviert und Administratoren sehen den Abschnitt "ApiKey" unter ihrem Profil nicht mehr.

Einstellungen

Wurde die REST Schnittstelle im "appsettings.json" aktiviert, finden Administratoren einen neuen Bereich in den Globalen Einstellungen über den die REST Schnittstelle jederzeit aktiviert und deaktiviert werden kann.

REST Schnittstelle aktivieren:

Diese Option aktiviert die Endpunkte der REST Schnittstelle. Ist diese Option deaktiviert, dann nimmt die REST Schnittstelle keine Request entgegen.

SwaggerUI aktivieren:

Diese Option aktiviert die SwaggerUI, dabei handelt es sich um eine interaktive Dokumentation der REST Schnittstelle. Sie kann unter "/swagger" erreicht werden.

Diese Option hat keine Auswirkung auf die Funktionalität der REST Schnittstelle. Wird sie deaktiviert, funktioniert die REST Schnittstelle, sofern sie aktiviert ist, trotzdem.

Diese Seite ist nur für Entwickler relevant die mit der REST Schnittstelle kommunizieren möchten.

Wird die Dokumentation nicht mehr benötigt, sollte die SwaggerUI Seite deaktiviert werden.

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.

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.

ApiKeys können mit einem Ablaufdatum erstellt werden. Wenn der ApiKey abläuft, können mit ihm keine Requests mehr durchgeführt werden.

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.

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

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.