...
Info |
---|
Die REST-API der PICTURE-Prozessplattform stellt eine programmatische Schnittstelle für die Interaktion mit ausgewählten Teilen des Datenmodells der PICTURE-Prozessplattform zur Verfügung, welche für typische Integrationsszenarien zur Einbindung von Drittsystemen relevant sind. Der folgende Abschnitt des Informationsportals richtet sich an Techniker, die eine Integration von Drittanwendungen mit der PICTURE-Prozessplattform prüfen, konzipieren und realisieren möchten. Dazu stehen auf den folgenden Seiten Informationen zu folgenden Themen zur Verfügung:
|
Um die REST-API in vollem Umfang nutzen zu können ist die Lizensierung des Portal-Moduls für Ihren Mandanten der PICTURE-Prozessplattform erforderlich.
Grundlagen
Die Programmierschnittstelle der Prozessplattform ist in Anlehnung an die Konventionen für eine RESTful-HTTP-API gestaltet. Sie weist insbesondere die folgenden Eigenschaften auf:
alle verfügbaren Operationen werden auf HTTP-Verben (GET, POST, PUT, DELETE etc.) abgebildet
alle Ressourcen lassen sich anhand ihrer URL eindeutig identifizieren.
Gegenüber der "reinen Lehre" bzgl. RESTful HTTP sind bei der Nutzung der API an folgenden Punkten Abweichungen zu erwarten:
Zustandslosigkeit: Die Zugriffe auf die API sind zwar zustandslos hinsichtlich der durch einen
RessourceRessourcen-Aufruf modellierten Fachlichkeit, die Authentifizierung/Autorisierung des Aufrufers erfolgt jedoch session-basiert (Ausnahme: Portalzugriffe auf Basis von "Share Tokens").
Repräsentationsformate für Nutzdaten (Inhalte von Request- und Response-Bodies): In der Regel liegen die Rückgabewerte im JSON-Format vor, in einigen Fällen in XML. Es findet keine Content Negotiation statt. Welches Format jeweils zurückgeliefert wird, kann der Dokumentation der einzelnen Endpunkte entnommen werden.
Hypermedia as the engine of application state: Eine Verlinkung der verschiedenen Ressourcen-Repräsentationen inkl. Auflistung der für eine Ressource jeweils möglichen Operationen findet nicht statt. Zur Formulierung gültiger
RequestRequests wird daher die Kenntnis der in dieser Dokumentation beschriebenen REST-Endpunkte, ihrer Semantik und ihres URL-Adressierungsschemas vorausgesetzt.
Querschnittliche Aspekte der Nutzung
Authentifizierung & Autorisierung
Für Authentifizierung und Autorisierung unterstützt die Schnittstelle die folgenden beiden Vorgehensweisen:
Session-basierte Authentifizierung auf Basis eines Benutzerkontos
Authentifizierung per Access-Token im URL-Parameter auf Basis einer Portal-Freigabe.
Welche Vorgehensweise für einen bestimmten REST-Endpunkt zur Verfügung steht, ist in der jeweiligen Endpunkt-Dokumentation im Abschnitt "Möglichkeiten zur Authentifizierung & Autorisierung" angegeben.
Session-basierte Authentifizierung
Für den Zugriff wird ein Benutzerkonto inkl. dessen Zugangsdaten (Benutzername und Passwort) benötigt.
Die Authentifizierung mit diesem Benutzerkonto erfolgt durch einen programmatischen Login mit den Zugangsdaten des Benutzerkontos über einen REST-Endpunkt (die Verbindung ist hierbei grundsätzlich per HTTPS-Verschlüsselung geschützt). Nach erfolgreichem Login erzeugt der Login-Endpunkt ein Session-Cookie und sendet dieses an den Aufrufer zurück.
Zugriffe auf sämtliche Ressourcen (abgesehen vom REST-Endpunkt für den Login selbst) setzen eine HTTP-Session voraus, die sich in die Prozessplattform eingeloggt hat. Hierzu muss bei jedem HTTP-Request auf eine geschützte Ressource das beim Login erhaltenen Session-Cookies im Header des Requests übermittelt werden.
Für sämtliche Zugriffe auf geschützte Ressourcen wird zum Zwecke der Autorisierungsprüfung der Rechte-Kontext des eingeloggten, mit der HTTP-Session verknüpften Benutzerkontos ausgewertet.
Die HTTP-Session wird von der Prozessplattform automatisch nach 20 Minuten Inaktivität getrennt.
Erfolgt kein expliziter Logout, so kann bis zum Ablauf der Session keine neue Session mit den Zugangsdaten aufgebaut werden (Mehrfach-Login-Schutz).
Authentifizierung per "Share Token" (Portal-Freigabe)
Ist für einen Prozessplattform-Mandanten zusätzlich das optionale Erweiterungspaket "Portalmodul" lizensiert, so steht zusätzlich zur session-basierten Authentifizierung für ausgewählte REST-Endpunkte die Möglichkeit zur Authentifizierung per Share Token zur Verfügung.
Diese Art des Zugriffs kann für alle Inhalte genutzt werden, für die eine Portal-Freigabe erstellt wurde.
Eine Freigabe in der Prozessplattform umfasst eine Menge von Prozessen / Prozesslandkarten. Die Authentifizierung des Zugriffs erfolgt über das Share Token der Freigabe, welches den Query-Parametern (&shareToken=...) des zugehörigen Freigabelinks entnommen werden kann (siehe dazu Freigaben verwalten).
Der Zugriff auf die Freigabe kann in der Prozessplattform per Whitelisting auf bestimmte IP-Adressbereiche begrenzt werden.
REST-Endpunkte
Auszug einfügen | ||||||
---|---|---|---|---|---|---|
|
Datenmodell
Allgemeine Fehlercodes
HTTP-Response-Code | mögliche Fehlerursache |
---|---|
400 | ungültige Anfrage |
401 | Login erforderlich / Session-Cookie ist nicht mitgesendet worden |
403 | Dem verwendeten Nutzerkonto fehlen Berechtigungen zum Zugriff auf die Ressource |
404 | Zur angefragten ID liegt kein Inhalt (mehr) vor |