VISIONAPI

Mit VISIONAPI können Sie VISIONWEB sowie die evoVIU-Kamerasysteme VIU1 und VIU2 einfach und zeitgemäß über eine HTTP-REST-Schnittstelle steuern. Die API bietet Ihnen Zugriff auf sämtliche Funktionen, die auch direkt an der Kamera oder über die Weboberfläche verfügbar sind, und lässt sich flexibel in eigene Anwendungen oder Systeme integrieren.

Die ausführlichste und aktuellste Funktionsbeschreibung finden Sie im Swagger der Anwendung. Dort sind alle Endpunkte, Parameter und Antwortformate übersichtlich dokumentiert. Zusätzlich ermöglicht der Swagger, API-Funktionen direkt zu testen und die Rückmeldungen in Echtzeit einzusehen.

First Steps VISIONAPI

Am einfachsten erreichen Sie den Swagger über die Startseite der evoVIU-Anwendung – klicken Sie dazu einfach auf „OPEN VISION API“.

Sie können den VISIONWEB Swagger auch direkt im Browser über den folgenden Link öffnen:

http://<DeineIPAdresse>/api/docs/

Sie gelangen zur Oberfläche des Swagger-Dokuments, in dem alle Endpunkte, Parameter und Rückgabewerte automatisch generiert und übersichtlich dargestellt sind.

Authentication

Um mit dem Swagger arbeiten zu können, müssen Sie sich – ähnlich wie bei der Anmeldung an der Kamera – auch im Swagger anmelden.

Als angemeldeter Nutzer im VISIONWEB werden die ersten Schritte – sofern kein aktives Login erforderlich ist – in der Regel automatisch ausgeführt. Zunächst wird ein Token abgerufen, mit dem anschließend alle weiteren API-Aufrufe durchgeführt werden können.

Generell gibt es im Swagger zwei Möglichkeiten zur Authentifizierung:

1. Anmeldung über permamente User-Token siehe User Management

2. Abrufen eines Session-Tokens und anschließende Verwendung dieses Tokens für die API-Aufrufe.

Unabhängig von der gewählten Methode erfolgt die Eingabe über den Authorize-Button oben rechts in der Swagger-Oberfläche. In beiden Fällen wird ein Bearer Token verwendet, das bei jedem API-Aufruf zur Authentifizierung mitgesendet wird.

Kurzübersicht Token

Standardmäßig sind in der Kamera folgende Anmeldedaten für den Master-Benutzer hinterlegt:

Wir empfehlen, das Passwort des Benutzers „Master“ unmittelbar nach Erhalt der Kamera zu ändern, um das System vor unbefugtem Zugriff zu schützen.

Falls Sie unter User Management, einen eigenen Token erstellt haben, können Sie diesen ebenfalls – unabhängig vom Master-Benutzer – für Ihre API-Aufrufe verwenden.
Der Vorteil: In der Anwendung wird Ihnen angezeigt, wenn die API auf die Kamera zugreift.

Beispiel:

Bitte beachten Sie, welche Grants (Berechtigungen) Sie dem Token bei der Erstellung zuweisen. Handelt es sich lediglich um die Rolle Viewer, stehen nur wenige API-Endpunkte zur Verfügung.

Anders verhält es sich bei den eigentlichen Session-Tokens: Diese werden beim Aufrufen des Swaggers bzw. der VISIONWEB-Plattform automatisch generiert. Ohne Nutzung sind sie für 10 Minuten aktiv; bei fortlaufender Nutzung verlängert sich die Gültigkeit entsprechend.

Bei der Nutzung des Calls:

POST https://<DeineIpAdresse>/api/v1/authentication/sessions/start

erhält man als Rückantwort folgende JSON-Inhalt. Dessen Value ist der Token, dann man zur Verwendung nutzen kann:

{
  "sessionTokenId": "c991a721-0a56-4e73-822f-215756ed8c2b",
  "activeUntil": "2025-08-09T20:58:15.514Z",
  "created": "2025-08-09T20:48:15.514Z",
  "value": "1d115d39-8078-46ae-ac9e-330e55903670"
}

Sessions Token:

"value": "1d115d39-8078-46ae-ac9e-330e55903670"

Swagger Authorization

Wenn Sie sich über Authorize anmelden, geben Sie den Token einfach in die dafür vorgesehene Eingabemaske ein, um die Authentifizierung durchzuführen.

Herzlichen Glückwunsch! Sie sind nun über den Swagger angemeldet

Bearbeitungsmodus “Active State”

Ähnlich wie bei VISIONWEB selbst kann immer nur ein Nutzer gleichzeitig Änderungen an der Kamera vornehmen. Dies gilt auch für die API, wenn sie bestimmte Operationen ausführen soll.
Allgemeine GET-Funktionen benötigen in der Regel keine Bearbeitungsrechte (Editor). Wenn Sie also lediglich Daten abrufen möchten, müssen Sie nicht zwingend im „Editiermodus“ sein.
Die einzelnen Funktionen im Swagger geben Ihnen jedoch genau an, in welchem Modus Sie sich befinden müssen und welche Grants (Berechtigungen) erforderlich sind.

Beispiel 1: Die GET-Funktion Health ist für Nutzer mit Viewer-Grant einsehbar und erfordert keinen aktiven Bearbeitungsmodus.

Beispiel 2: Die PUT-Funktion Filesystem/Config ist nur für Nutzer mit dem Editor-Grant und höher zulässig und kann nur im aktiven Bearbeitungsmodus ausgeführt werden.

Beispiel 3: Die PUT-Funktion network/bridging kann ausschließlich von Nutzern mit Administrator-Grant im aktiven Bearbeitungsmodus ausgeführt werden.

Nutzerrolle im VISIONWEB vs. Grant im VISIONAPI

Wenn eine Funktion mit „active“ gekennzeichnet ist, muss der Aufruf im Bearbeitungsmodus erfolgen; andernfalls ist dies nicht erforderlich.

Um in den ActiveState zu gelangen, muss dieser zunächst angefordert werden. Dies erfolgt nach der Autorisierung über den folgenden Befehl:

POST https://<DeineIpAdresse>/api/v1/authentication/sessions/current/requestActiveStatus?force=true

Der Statuscode 204 bestätigt, dass das Einloggen im Bearbeitungsmodus erfolgreich war.

Herzlichen Glückwunsch – Sie können nun auch über den Swagger Funktionen ausführen, die ausschließlich im Bearbeitungsmodus verfügbar sind. Ab jetzt können Sie jede einzelne Funktion – wie im Swagger beschrieben – testen und ausprobieren.