REST API Erste Schritte

Für die Anbindung von Scopevisio an andere Systeme zur Automation bietet Scopevisio eine umfassende REST API an. Hier werden die ersten Schritte zur Nutzung der REST API beschrieben.

Die Zielgruppe für die hier beschriebene Nutzung der REST API sind Kunden, die Scopevisio auf einfachem Wege in die Automation ihrer bestehenden Systeme einbinden wollen. Wollen Sie als Kunde einen Drittanbieter an Ihre Gesellschaft anbinden oder sind Sie selbst Drittanbieter und wollen mit Scopevisio einen Mehrwert für unsere Kunden schaffen? Melden Sie sich gerne bei unserem Support für die Authentifizierung über OAuth2.

Erstellung eines technischen Nutzers (optional)

Um die REST API zu nutzen wird ein aktiver Nutzer in einer Scopevisio Gesellschaft benötigt. Für die dauerhafte Nutzung im Rahmen von Automation empfehlen wir die Erstellung eines technischen Nutzers, z.B. über eine funktionale E-Mail-Adresse wie scopevisio-automation@example.com. Das E-Mail-Postfach des technischen Nutzers sollte in der IT-Infrastruktur des Scopevisio Kunden angelegt werden. Nach Erstellung, kann der technische Nutzer wie gewohnt der Scopevisio Gesellschaft hinzugefügt und mit benötigten Lizenzen und Rechten ausgestattet werden.

Generierung von Access Token

Zur Nutzung der REST API mit einem Nutzer wird ein Access Token benötigt. Dieser kann mittels Kommandozeile oder Swagger UI erstellt werden.

Token mittels Kommandozeile erstellen (curl)

Ein Access Token für die REST API kann mittels Kommandozeile erstellt werden. Über folgenden exemplarischen Befehl mit curl wird ein Access Token für einen Nutzer erstellt:

curl -X 'POST' 
   'https://appload.scopevisio.com/rest/token' -d 
   'grant_type=password&customer=<7-digit-cusomer-number>
   &username=<user-email>&password=<user-password>&organisation=<organisation-name>'

Dabei sind die Platzhalter <7-digit-cusomer-number>, <user-email>, <user-password> und <organisation-name> durch entsprechende Werte zu ersetzen.

In der Antwort auf die Anfrage findet sich neben dem kurzlebigen Access Token auch ein langlebiger Refresh Token, der zukünftig zur Aktualisierung abgelaufener Access Token genutzt werden kann. Dies verhindert die Eintragung von Nutzernamen und Passwörtern in Applikationen zur Automation. Weitere Informationen dazu finden sich in der Dokumentation des /token Endpunktes.

Token mittels Swagger UI erstellen

Alternativ kann ein Access Token für die REST API auch mittels unserer Swagger UI erstellt werden. Dazu werden beim /token Endpunkt die nötigen Pflichtfelder customer, username, organisation und password ausgefüllt und der Aufruf mittels “Execute” gestartet.

REST API Endpunkt aufrufen

Mittels Access Token kann nun die Scopevisio REST API angesprochen werden. Eine Dokumentation der Endpunkte findet sich in unserer Swagger UI.

Der Aufruf des Endpunktes /myaccount liefert beispielsweise Informationen zum aktiven Nutzer.

curl -X 'GET' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer <ACCESS TOKEN>' \
  'https://appload.scopevisio.com/rest/myaccount'

Access Token invalidieren

Um die generierten Token zu invalidieren, melden Sie sich mit Ihren Zugangsdaten in der Kundenlounge unter https://appload.scopevisio.com/apps/public/login.html an und navigieren zum Punkt “Meine REST API Clients”. Hier werden die generierten Token aufgelistet und können widerrufen werden.